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Foreword 



CP/M® 3 is a microcomputer operating system designed for the Intel® 8080, Intel 
8085, or other compatible microprocessor. To run CP/M 3, your computer must 
have an ASCII console, which includes a keyboard and screen, or another display 
device, from one to sixteen disk drives and a minimum of 32K of memory space. To 
support additional memory beyond the 64K addressing limit of the processors listed 
above, CP/M 3 can also support bank-switched memory. The minimum memory 
requirement for a banked system is 96K. 

This manual describes the programming environment of CP/M 3, and is written 
for experienced programmers who are writing application software in the CP/M 3 
environment. It assumes you are familiar with the system features and utilities described 
in the CP/M Plus (CP/M Version 3) Operating System User's Guide and the 
Programmer's Utilities Guide for the CP/M Family of Operating Systems. It also 
assumes that your CP/M 3 system has been customized for your computer's hard- 
ware and is executing as described in the CP/M Plus (CP/M Version 3) Operating 
System User's Guide. If you need to customize your system, please refer to the CP/M 
Plus (CP/M Version 3) Operating System System Guide. 

Section 1 of this manual describes the components of the operating system, where 
they reside in memory, and how they work together to provide a standard operating 
environment for application programs. Section 2 describes how an application pro- 
gram can call on CP/M 3 to perform serial input and output and manage disk files. 
Section 3 provides a detailed description of each operating system function. Section 
4 presents example programs. 

The CP/M Plus (CP/M Version 3) Operating System Programmer's Guide contains 
five appendixes. Appendix A describes the CP/M 3 System Control Block, and defines 
its fields. Appendix B supplies the format for the Page Relocatable Program. Appen- 
dix C tells you how to generate System Page Relocatable files. Appendix D lists the 
ASCII Symbol Table, and Appendix E summarizes BDOS functions. 
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Section 1 
Introduction to CP/M 3 



This section introduces you to the general features of CP/M 3 with an emphasis 
on how CP/M 3 organizes your computer's memory. The section begins by describing 
the general memory organization of banked and nonbanked systems and defines the 
programming environment they have in common. It then shows how CP/M 3 defines 
memory space into standard regions for operating system modules and executing 
programs. Subsequent paragraphs describe the components of the operating system, 
how they communicate with each other and the application program, and in greater 
detail where each component and program is located in memory. After a brief intro- 
duction to disk organization, the final section gives examples of system operation. 

CP/M 3 is available in two versions: a version that supports bank-switched mem- 
ory, and a version that runs on nonbanked systems. CP/M 3 uses the additional 
memory available in banked systems to provide functions that are not present in the 
nonbanked version. For example, the banked version of CP/M 3 supports file pass- 
words; the nonbanked version does not. However, because a nonbanked system 
treats passwords the same way as a banked system does when password protection 
is not enabled, an application program can run under either system without modifi- 
cation. 
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1.1 Banked and Nonbanked Memory Organization 

The memory organization for a nonbanked CP/M 3 system is very simple, as 
shown in Figure 1-1. 



TOP OF MEMORY 1 



LOW MEMORY 
(0000H) 




Figure 1-1. Nonbanked System Memory Organization 



In the nonbanked organization, physical memory consists of a single, contiguous 
region addressable from 0000H up to a maximum of OFFFFH (64K-1). The shaded 
region below the operating system represents the memory space available for the 
loading and execution of transient programs. The clear area above the operating 
system represents space that GENCPM can allocate to the operating system for disk 
record buffers and directory hash tables, as described in the CP/M Plus (CP/M Ver- 
sion 3) Operating System System Guide. The minimum size of this area is determined 
by the specific hardware requirements of the host microcomputer system. 
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1.1 Banked/Nonbanked Organization 



To expand memory capacity beyond the 64K address space of an 8-bit micropro- 
cessor, CP/M 3 supports bank-switched memory in a special version called the banked 
system. In the banked version, the operating system is divided into two modules: the 
resident portion and the banked portion. The resident portion resides in common 
memory; the banked portion resides just below the top of banked memory in Bank 0. 
Figure 1-2 shows memory organization under the banked system. 



TOP OF MEMORY *- 



(COMMON) — 



TOP OF BANKED 
MEMORY 



(BANK SWITCHED) - 



LOW MEMORY 

(0000H) »-L 




BUFFERS 



O.S. 



BANKED 
O.S. 




BANKO BANK1 

Figure 1-2. Banked System Memory Organization 



BANKN 



In Figure 1-2, Bank is switched in or in context. The top region of memory, the 
common region, is always in context; that is, it can always be referenced, no matter 
what bank is switched in. Figure 1-3 shows memory organization when Bank 1 is in 
context. 
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TOP OF MEMORY 



(COMMON) - 



TOP OF BANKED 
MEMORY 



(BANK SWITCHED) - 



LOW MEMORY 
(0000H) 



BANKED 
O.S. 




BANKO 



BANK1 



BANK N 



Figure 1-3. Banked Memory with Bank 1 in Context 



From a transient program's perspective, Bank 1 is always in context. The operating 
system can switch to Bank or other banks when performing operating system 
functions without affecting the execution of the transient program. Any bank-switch- 
ing performed by the operating system is completely transparent to the calling pro- 
gram. Because the major portion of the operating system resides in Bank in banked 
systems, more memory space is available for transient programs in banked CP/M 3 
systems than in nonbanked systems. 

The operating system uses the clear areas in Figures 1-2 and 1-3 for disk record 
buffers and directory hash tables. The clear area in the common region above the 
operating system represents space that can be allocated for data buffers by GENCPM. 
Again, the minimum size of this area is determined by the specific hardware require- 
ments of the host microcomputer system. 
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1.1 Banked/Nonbanked Organization 



The banked version of CP/M 3 requires a minimum of two banks, Bank and 
Bank 1, and can support up to 16 banks of memory. Bank numbers are generally 
arbitrary with the following exceptions: Bank is the system bank and is in context 
when CP/M 3 is started. Bank 1 is the transient program bank, and must be contig- 
uous from location zero to the top of banked memory. This requirement does not 
apply to the other banks. However, common memory must be contiguous. 

The size of the common region is typically 16K. The only size requirement on the 
common region is that it must be large enough to contain the resident portion of the 
operating system. The maximum top of memory address for both banked and non- 
banked systems is 64K-1 (OFFFFH). 

In summary, no matter how physical memory is configured, or whether the oper- 
ating system is banked or nonbanked, CP/M 3 always organizes memory logically so 
that to a transient program in any CP/M 3 system, memory appears as shown in 
Figure 1-4. 



TOP OF MEMORY *• 



LOW MEMORY 

(OOOOH)^ 




Figure 1-4. CP/M 3 Logical Memory Organization 



1.2 System Components 

Functionally, the CP/M 3 operating system is composed of distinct modules. Tran- 
sient programs can communicate with these modules to request system services. Fig- 
ure 1-5 shows the regions where these modules reside in logical memory. Note that 
from the transient program's perspective, Figure 1-5 is just a more detailed version 
of Figure 1-4. 



U DIGITAL RESEARCH 1 



1-5 



1.2 System Components 



CP/M 3 Programmer's Guide 



HIGH MEMORY: 

BIOS_BASE: 

BDOS_BASE: 

LOADER_BASE: 

RSX_BASE: 

0100H: 
0OO0H: 



BIOS : BASIC INPUT/OUTPUT SYSTEM 



BDOS : BASIC DISK OPERATING SYSTEM 



LOADER : PROGRAM LOADER MODULE 



RSX(s) : RESIDENT SYSTEM EXTENSIONS 



TPA : TRANSIENT PROGRAM AREA 



CCP : CONSOLE COMMAND PROCESSOR 



PAGE ZERO 



Figure 1-5. System Components and Regions in Logical Memory 



The Basic Input/Output System, BIOS, is a hardware-dependent module that defines 
the low-level interface to a particular computer system. It contains the device-driving 
routines necessary for peripheral device I/O. 

The Basic Disk Operating System, BDOS, is the hardware-independent module that 
is the logical nucleus of CP/M 3. It provides a standard operating environment for 
transient programs by making services available through numbered system function 
calls. 

The LOADER module handles program loading for the Console Command Proces- 
sor and transient programs. Usually, this module is not resident when transient pro- 
grams execute. However, when it is resident, transient programs can access this 
module by making BDOS Function 59 calls. 

Resident System Extensions, RSXs, are temporary additional operating system 
modules that can selectively extend or modify normal operating system functions. 
The LOADER module is always resident when RSXs are active. 
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The Transient Program Area, TPA, is the region of memory where transient pro- 
grams execute. The CCP also executes in this region. 

The Console Command Processor, CCP, is not an operating system module, but is 
a system program that presents a human-oriented interface to CP/M 3 for the user. 

The Page Zero region is not an operating system module either, but functions 
primarily as an interface to the BDOS module from the CCP and transient programs. 
It also contains critical system parameters. 

1.3 System Component Interaction and Communication 

This section describes interaction and communication between the modules and 
regions defined in Section 1.2. The most significant channels of communication are 
between the BDOS and the BIOS, transient programs and the BDOS, and transient 
programs and RSXs. 

The division of responsibility between the different modules and the way they 
communicate with one another provide three important benefits. First, because the 
operating system is divided into two modules — one that is configured for different 
hardware environments, and one that remains constant on every computer — CP/M 3 
software is hardware independent; you can port your programs unchanged to differ- 
ent hardware configurations. Second, because all communication between transient 
programs and the BDOS is channeled through Page Zero, CP/M 3 transient programs 
execute, if sufficient memory is available, independent of configured memory size. 
Third, the CP/M 3 RSX facility can customize the services of CP/M 3 on a selective 
basis. 

1.3.1 The BDOS and BIOS 

CP/M 3 achieves hardware independence through the interface between the BDOS 
and the BIOS modules of the operating system. This interface consists of a series of 
entry points in the BIOS that the BDOS calls to perform hardware-dependent primi- 
tive functions such as peripheral device I/O. For example, the BDOS calls the CONIN 
entry point of the BIOS to read the next console input character. 

A system implementor can customize the BIOS to match a specific hardware envi- 
ronment. However, even when the BIOS primitives are customized to match the host 
computer's hardware environment, the BIOS entry points and the BDOS remain 
constant. Therefore, the BDOS and the BIOS modules work together to give the CCP 
and other transient programs hardware-independent access to CP/M 3's facilities. 



m DIGITAL RESEARCH 7 



1-7 



1.3 Component Interaction CP/M 3 Programmer's Guide 



1.3.2 Applications and the BDOS 

Transient programs and the CCP access CP/M 3 facilities by making BDOS func- 
tion calls. BDOS functions can create, delete, open, and close disk files, read or write 
to opened files, retrieve input from the console, send output to the console or list 
device, and perform a wide range of other services described in Section 3,"BDOS 
Functions." 

To make a BDOS function call, a transient program loads CPU registers with 
specific entry parameters and calls location 0005 H in Page Zero. If RSXs are not 
active in memory, location 0005H contains a jump instruction to location 
BDOS_base -I- 6. If RSXs are active, location 0005H contains a jump instruction to 
an address below BDOS_base. Thus, the Page Zero interface allows programs to run 
without regard to where the operating system modules are located in memory. In 
addition, transient programs can use the address at location 0006H as a memory 
ceiling. 

Some BDOS functions are similar to BIOS entry points, particularly in the case of 
simple device I/O. For example, when a transient program makes a console output 
BDOS function call, the BDOS makes a BIOS console output call. In the case of disk 
I/O, however, this relationship is more complex. The BDOS might call many BIOS 
entry points to perform a single BDOS file I/O function. 

Transient programs can terminate execution by jumping to location 0000H in the 
Page Zero region. This location contains a jump instruction to BIOS_base + 3, which 
contains a jump instruction to the BIOS warm start routine. The BIOS warm start 
routine loads the CCP into memory at location 100H and then passes control to it. 

The Console Command Processor is a special system program that executes in the 
TPA and makes BDOS calls just like an application program. However, the CCP has 
a unique role: it gives the user access to operating system facilities while transient 
programs are not executing. It includes several built-in commands, such as TYPE and 
DIR, that can be executed directly without having to be loaded from disk. When the 
CCP receives control, it reads the user's command lines, distinguishes between built- 
in and transient commands, and when necessary, calls upon the LOADER module to 
load transient programs from disk into the TPA for execution. Section 1.6.2 describes 
CCP operation in detail. 
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1.3.3 Applications and RSXs 

A Resident System Extension is a temporary additional operating system module. 
An RSX can extend or modify one or more operating system functions selectively. 
As with a standard BDOS function, a transient program accesses an RSX function 
through a numbered function call. 

At any one time there might be zero, one, or multiple RSXs active in memory. 
When a transient program makes a BDOS function call, and RSXs are active, each 
RSX examines the function number of the call. If the function number matches the 
function the RSX is designed to extend or modify, the RSX performs the requested 
function. Otherwise, the RSX passes the function request to the next RSX. Noninter- 
cepted functions are eventually passed to the BDOS for standard execution. 

RSXs are loaded into memory when programs containing RSXs are loaded. The 
CP/M 3 utility, GENCOM, can attach RSXs to program files. When attaching RSXs, 
GENCOM places a special one page header at the beginning of the program file. The 
CCP reads this header, learns that a program has attached RSXs, and loads the RSXs 
accordingly. The header itself is not loaded into memory; it merely indicates to the 
CCP that RSX loading is required. 

The LOADER module is a special type of RSX that supports BDOS function 59, 
Load Overlay. It is always resident when RSXs are active. To indicate RSX support 
is required, a program that calls function 59 must have an RSX header attached by 
GENCOM, even if the program does not require other RSXs. When the CCP 
encounters this type of header in a program file when no RSXs are active, it sets the 
address at location 0006H in Page Zero to LOADERbase + 6 instead of 
BDOS base + 6. 



1.4 Memory Region Boundaries 

This section reviews memory regions under CP/M 3, and then describes some 
details of region boundaries. It then relates the sizes of various modules to the space 
available for the execution of transient programs. Figure 1-6 reviews the location of 
regions in logical memory. 
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HIGH MEMORY: 
BIOS_BASE: 

BDOS_BASE: 
LOADEFLBASE: 



BIOS : BASIC I/O SYSTEM 



BDOS : BASIC DISK OPERATING SYSTEM 



LOADER : PROGRAM LOADER MODULE 



RSX(1) : RESIDENT SYSTEM EXTENSION 



RSX(N)_BASE: 



0100H: 



RSX(N) : RESIDENT SYSTEM EXTENSION 
'///. f PA : TRANSIENT PROGRAM AREA Jfffl 



0000H: 



CCP : CONSOLE COMMAND PROCESSOR 



PAGE ZERO 



Figure 1-6. System Modules and Regions in Logical Memory 



First note that all memory regions in CP/M 3 are page-aligned. This means that 
regions and operating system modules must begin on a page boundary. A page is 
defined as 256 bytes, so a page boundary always begins at an address where the low- 
order byte is zero. 

The term High Memory in Figure 1-6 denotes the high address of a CP/M 3 
system. This address may fall below the actual top of memory address if space above 
the operating system has been allocated for directory hashing or data buffering by 
GENCPM. The maximum top of memory address for both banked and nonbanked 
systems is 64K-1 (OFFFFH). 

The labels BIOS_base, BDOS_base, and LOADER_base represent the base addresses 
of the operating system regions. These addresses always fall on page boundaries. The 
size of the BIOS region is not fixed, but is determined by the requirements of the 
host computer system. 



m DIGITAL RESEARCH 1 



1-10 



CP/M 3 Programmer's Guide 1.4 Region Boundaries 

The size of the BDOS region differs for the banked and nonbanked versions of 
CP/M 3. In the banked version, the resident BDOS size is 6 pages, 1.5K. In the 
nonbanked system, the BDOS size ranges from 31 pages, 7.75K, to 33 pages, 8.25K, 
depending on system generation options and BIOS requirements. 

RSXs are page aligned modules that are stacked in memory below LOADER_base 
in memory. In the configuration shown in Figure 1-6, location 0005H of Page Zero 
contains a jump to location RSX(N)_base + 6. Thus, the memory ceiling of the TPA 
region is reduced when RSXs are active. 

Under CP/M 3, the CCP is a transient program that the BIOS loads into the TPA 
region of memory at system cold and warm start. The BIOS also loads the LOADER 
module at this time, because the LOADER module is attached to the CCP. When the 
CCP gains control, it relocates the LOADER module just below BDOS_base. The 
LOADER module handles program loading for the CCP. It is three pages long. 

The maximum size of a transient program that can be loaded into the TPA is 
limited by LOADER_base because the LOADER cannot load a program over itself. 
Transient programs may extend beyond this point, however, by using memory above 
LOADER_base for uninitialized data areas such as I/O buffers. Programs that use 
memory above BDOS_base cannot make BDOS function calls. 



1.5 Disk and Drive Organization and Requirements 

CP/M 3 can support up to sixteen logical drives, identified by the letters A through 
P, with up to 512 megabytes of storage each. A logical drive usually corresponds to 
a physical drive on the system, particularly for physical drives that support remova- 
ble media such as floppy disks. High-capacity hard disks, however, are commonly 
divided up into multiple logical drives. Figure 1-7 illustrates the standard organiza- 
tion of a CP/M 3 disk. 
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TRACK M 

DATA TRACKS 

TRACK N 

SYSTEM TRACKS 



TRACK 



CP/M 3 DATA REGION 



CP/M 3 DIRECTORY REGION 



CCP (OPTIONAL) 



CPMLDR 



COLD BOOT LOADER 



Figure 1-7. Disk Organization 



In Figure 1-7, the first N tracks are the system tracks. System tracks are required 
only on the disk used by CP/M 3 during system cold start or warm start. The 
contents of this region are described in Section 1.6.1. All normal CP/M 3 disk access 
is directed to the data tracks which CP/M 3 uses for file storage. 

The data tracks are divided into two regions: a directory area and a data area. The 
directory area defines the files that exist on the drive and identifies the data space 
that belongs to each file. The data area contains the file data defined by the directory. 
If the drive has adequate storage, a CP/M 3 file can be as large as 32 megabytes. 

The directory area is subdivided into sixteen logically independent directories. These 
directories are identified by user numbers through 15. During system operation, 
CP/M 3 runs with the user number set to a single value. The user number can be 
changed at the console with the USER command. A transient program can change 
the user number by calling a BDOS function. 

The user number specifies the currently active directories for all the drives on the 
system. For example, a PIP command to copy a file from one disk to another gives 
the destination file the same user number as the source file unless the PIP command 
is modified by the [G] option. 
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The directory identifies each file with an eight-character filename and a three- 
character filetype. Together, these fields must be unique for each file. Files with the 
same filename and filetype can reside in different user directories on the same drive 
without conflict. Under the banked version of CP/M 3, a file can be assigned an 
eight-character password to protect the file from unauthorized access. 

All BDOS functions that involve file operations specify the requested file by file- 
name and filetype. Multiple files can be specified by a technique called ambiguous 
reference, which uses question marks and asterisks as wildcard characters to give 
CP/M 3 a pattern to match as it searches the directory. A question mark in an 
ambiguous reference matches any value in the same position in the directory filename 
or filetype field. An asterisk fills the remainder of the filename or filetype field of the 
ambiguous reference with question marks. Thus, a filename and filetype field of all 
question marks, ????????.???, equals an ambiguous reference of two asterisks, *.*, 
and matches all files in the directory that belong to the current user number. 

The CP/M 3 file system automatically allocates directory space and data area space 
when a file is created or extended, and returns previously allocated space to free 
space when a file is deleted or truncated. If no directory or data space is available for 
a requested operation, the BDOS returns an error to the calling program. In general, 
the allocation and deallocation of disk space is transparent to the calling program. 
As a result, you need not be concerned with directory and drive organization when 
using the file system facilities of CP/M 3. 



1.6 System Operation 

This section introduces the general operation of CP/M 3. This overview covers 
topics concerning the CP/M 3 system components, how they function and how they 
interact when CP/M 3 is running. This section does not describe the total function- 
ality of CP/M 3, but simply introduces basic CP/M 3 operations. 

For the purpose of this overview, CP/M 3 system operation is divided into five 
categories. First is system cold start, the process that begins execution of the operat- 
ing system. This procedure ends when the Console Command Processor, CCP, is 
loaded into memory and the system prompt is displayed on the screen. Second is the 
operation of the CCP, which provides the user interface to CP/M 3. Third is transient 
program initiation, execution and termination. Fourth is the way Resident System 
Extensions run under CP/M 3. The fifth and final category describes the operation of 
the CP/M 3 SUBMIT utility. 
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1.6.1 Cold Start Operation 

The cold start procedure is typically executed immediately after the computer is 
turned on. The cold start brings CP/M 3 into memory and gives it control of the 
computer's resources. Cold start is a four-stage procedure. 

In the first stage, a hardware feature, or ROM-based software associated with 
system reset, loads a small program, called the Cold Boot Loader, into memory from 
the system tracks of drive A (see figure 1-6). The Cold Boot Loader is usually 128 or 
256 bytes long. 

The Cold Boot Loader performs the second stage of the cold start process. It loads 
the CP/M 3 loader program, CPMLDR, into memory from the system tracks of the 
system disk and passes control to it. During this stage, the Cold Boot Loader can 
also perform other tasks, such as initializing hardware dependent I/O ports. 

CPMLDR performs the third stage in the cold start process. First, it reads the 
CPM3.SYS file from the data area of the disk. The CPM3.SYS file, which is created 
by the CP/M 3 system generation utility GENCPM, contains the BDOS and BIOS 
system components and information indicating where these modules are to reside in 
memory. Once CPMLDR has loaded the BDOS and BIOS into memory, it sends a 
sign-on message to the console and passes control to the BIOS Cold Boot entry point. 
If specified as a GENCPM option, CPMLDR can also display a memory map of the 
CP/M 3 system. 

CPMLDR is a small, self-contained version of CP/M 3 that supports only console 
output and sequential file input. Consistent with CP/M 3's organization, it contains 
two modules, an invariant CPMLDR_BDOS, and a variant CPMLDR_BIOS that is 
adapted to match the host microcomputer hardware environment. Cold start initiali- 
zation of I/O ports and similar functions can also be performed in the CPMLDR_BIOS 
module during the third stage of cold start. 

In the banked version of CP/M 3, these first three stages of the cold boot procedure 
are performed with Bank in context. The BIOS Cold Start function switches in 
Bank 1 before proceeding to stage four. 
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The fourth and final stage in the cold start procedure is performed by the BIOS 
Cold Start function, Function 0. The entry point to this function is located at 
BIOS_base as described in Section 1.4. The BIOS Cold Start function begins by 
performing any remaining hardware initialization, and initializing Page Zero. To 
initialize Page Zero, the BIOS Cold Start function places a jump to BIOS_base + 3, 
the BIOS Warm Start entry point, at location 0000H, and a jump to BDOS_base + 6, 
the BDOS entry point, at location 0005H in memory. 

The BIOS Cold Start function completes the fourth stage by loading the CCP into 
the TPA region of memory and passing control to it. The CCP can be loaded from 
one of two locations. If there is sufficient space in the system tracks for the CCP, it 
is usually loaded from there. If there is not enough space in the system tracks, the 
BIOS Cold Start function can read the CCP from the file CCP.COM. 

On some banked systems, the CCP is also copied to an alternate bank, so that 
warm start operations can copy the CCP into the TPA from memory. This speeds up 
the system warm start operation, and makes it possible to warm start the system 
without having to access a system disk. 

When the CCP gains control, it displays a prompt that references the default disk. 
If a PROFILE. SUB submit file is present on the default drive, the CCP executes this 
submit file before prompting the user for a command. 

At this point, the cold start procedure is complete. Note that the user number is 
set to zero when CP/M 3 is cold started. However, the PROFILE submit file can set 
the user number to another value if this is desirable. 

The cold start procedure is designed so that the system tracks need to be initialized 
only once. This is accomplished because the system track routines are independent of 
the configured memory size of the CP/M 3 system. The Cold Boot Loader loads 
CPMLDR into a constant location in memory. This location is chosen when the 
system is configured. However, CPMLDR locates the BDOS and BIOS system com- 
ponents in memory as specified by the CPM3.SYS file. The CCP always executes at 
location 100H in the TPA. Thus, CP/M 3 allows the user to generate a new system 
with GENCPM, and then run it without having to update the system tracks of the 
system disk. 
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1.6.2 CCP Operation 

The Console Command Processor provides the user access to CP/M 3 facilities 
when transient programs are not running. It also reads the user's command lines, 
differentiates between built-in commands and transient commands, and executes the 
commands accordingly. 

This section describes the responsibilities and capabilities of the CCP in some 
detail. The section begins with a description of the CCP's activities when it first 
receives control from the Cold Start procedure. The section continues with a general 
discussion of built-in commands, and concludes with a step-by-step description of 
the procedure the CCP follows to execute the user's commands. 

When the CCP gains control following a cold start procedure, it displays the 
system prompt at the console. This signifies that the CCP is ready to execute a 
command. The system prompt displays the letter of the drive designated as the initial 
default drive during GENCPM operation. For example, if drive A was specified as 
the initial default drive, the CCP displays the following prompt: 

A> 

After displaying the system prompt, the CCP scans the directory of the default drive 
for the file PROFILE.SUB. If the file exists, the CCP creates the command line 
SUBMIT PROFILE; otherwise the CCP reads the user's first command line by mak- 
ing a BDOS Read Console Buffer function call (BDOS Function 10). 

The CCP accepts two different command forms. The simplest CCP command form 
changes the default drive. The following example illustrates a user changing the 
default drive from A to B. 

A>6; 
B> 

This command is one of the CCP's built-in commands. Built-in commands are part 
of the CCP. They reside in memory while the CCP is active, and therefore can be 
executed without referencing a disk. 
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The second command form the CCP accepts is the standard CP/M command line. 
A standard CP/M command line consists of a command keyword followed by an 
optional command tail. The command keyword and the command tail can be typed 
in any combination of upper-case and lower-case letters; the CCP converts all letters 
in the command line to upper-case. The following syntax defines the standard CP/M 
command line: 

<command> <command tail> 

where 

<command> = > <filespec> or 

<built-in> 

<command tail> = > (no command tail) or 

<filespec> or <filespec><delimiter><filespec> 

<filespec> => {d:}filename{.typ}{;password} 

<built-in> = > one of the CCP built-in commands 

<delimiter> = > one or more blanks or a tab or one of the 

following:" = ,[]<>" 

d: = > CP/M 3 drive specification,"A"through"P" 

filename = > 1 to 8 character filename 

typ = > 1 to 3 character filetype 

password = > 1 to 8 character password value 

Fields enclosed in curly brackets are optional. If there is no drive {d:} present in a file 
specification <filespec>, the default drive is assumed. If the type field {.typ} is omit- 
ted, a type field of all blanks is implied. Omitting the password field {;password} 
implies a password of all blanks. When a command line is entered at the console, it 
is terminated by a return or line-feed keystroke. 

Transient programs that run under CP/M 3 are not restricted to the above com- 
mand tail definition. However, the CCP only parses command tails in this format for 
transient programs. Transient programs that define their command tails differently 
must perform their own command tail parsing. 
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The command field must identify either a built-in command, a transient program, 
or a submit file. For example, USER is the keyword that identifies the built-in com- 
mand that changes the current user number. The CP/M 3 CCP displays the user 
number in the system prompt when the user number is non-zero. The following 
example illustrates changing the user number from zero to 15. 

B>USER 15 
15B> 

The following table summarizes the built-in commands. 



Table 1-1. CP/M 3 Built-in Commands 



Command 


Meaning 


DIR 


displays a list of all filenames from a disk directory except those 
marked with the SYS attribute. 


DIRSYS 


displays a filename list of those files marked with the SYS 
attribute in the directory. 


ERASE 


erases a filename from a disk directory and releases the storage 
occupied by the file. 


RENAME 


renames a file. 


TYPE 


displays the contents of an ASCII character file at your console 
output device. 


USER 


changes from one user number to another. 



Some built-in commands have associated command files which expand upon the 
options provided by the built-in command. If the CCP reads a command line and 
discovers the built-in command does not support the options requested in the com- 
mand line, the CCP loads the built-in function's corresponding command file to 
perform the command. The DIR command is an example of this type of command. 
Simple DIR commands are supported by the DIR built-in directly. More complex 
requests are handled by the DIR.COM utility. 
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All command keywords that do not identify built-in commands identify either a 
transient program file or a submit file. If the CCP identifies a command keyword as 
a transient program, the transient program file is loaded into the TPA from disk and 
executed. If it recognizes a submit file, the CCP reconstructs the command line into 
the following form: 

SUBMIT <command> <command tail> 

and attempts to load and execute the SUBMIT utility. Thus, the original command 
field becomes the first command tail field of the SUBMIT command. Section 1.6.5 
describes the execution of CP/M 3's SUBMIT utility. The procedure the CCP follows 
to parse a standard command line and execute built-in and transient commands is 
described as follows: 

1. The CCP parses the command line to pick up the command field. 

2. If the command field is not preceded by a drive specification, or followed by 
a filetype or password field, the CCP checks to see if the command is a CCP 
built-in function. If the command is a built-in command, and the CCP can 
support the options specified in the command tail, the CCP executes the 
command. Otherwise, the CCP goes on to step 3. 

3. At this point the CCP assumes the command field references a command file 
or submit file on disk. If the optional filetype field is omitted from the com- 
mand, the CCP usually assumes the command field references a file of type 
COM. For example, if the command field is PIP, the CCP attempts to open 
the file PIP.COM. 

Optionally, the CP/M 3 utility SETDEF can specify that a filetype of SUB 
also be considered when the command filetype field is omitted. When this 
automatic submit option is in effect, the CCP attempts to open the command 
with a filetype of COM. If the COM file cannot be found, the CCP repeats 
the open operation with a filetype of SUB. As an alternative, the order of 
open operations can be reversed so that the CCP attempts to open with a 
filetype of SUB first. In either case, the file that is found on disk first deter- 
mines the filetype field that is ultimately associated with the command. 

If the filetype field is present in the command, it must equal COM, SUB or 
PRL. A PRL file is a Page Relocatable file used in Digital Research's multi- 
user operating system, MP/M™. Under CP/M 3, the CCP handles PRL files 
exactly like COM files. 
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If the command field is preceded by a drive specification {d:}, the CCP attempts 
to open the command or submit file on the specified drive. Otherwise, the 
CCP attempts to open the file on the drives specified in the drive chain. 

The drive chain specifies up to four drives that are to be referenced in sequence 
for CCP open operations of command and submit files. If an open operation 
is unsuccessful on a drive in the drive chain because the file cannot be found, 
the CCP repeats the open operation on the next drive in the chain. This 
sequence of open operations is repeated until the file is found, or the drive 
chain is exhausted. The drive chain contains the current default drive as its 
only drive unless the user modifies the drive chain with the CP/M 3 SETDEF 
utility. 

When the current user number is non-zero, all open requests that fail because 
the file cannot be found, attempt to locate the command file under user zero. 
If the file exists under user zero with the system attribute set, the file is 
opened from user zero. This search for a file under user zero is made by the 
BDOS Open File function. Thus, the user zero open attempt is made before 
advancing to the next drive in the search chain. 

When automatic submit is in effect, the CCP attempts to open with the first 
filetype, SUB or COM, on all drives in the search chain before trying the 
second filetype. 

In the banked system, if a password specified in the command field does not 
match the password of a file on a disk protected in Read mode, the CCP file 
open operation is terminated with a password error. 

If the CCP does not find the command or submit file, it echoes the command 
line followed by a question mark to the console. If it finds a command file 
with a filetype of COM or PRL, the CCP proceeds to step 4. If it finds a 
submit file, it reconstructs the command line as described above, and repeats 
step 3 for the command, SUBMIT.COM. 
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4. When the CCP successfully opens the command file, it initializes the follow- 
ing Page Zero fields for access by the loaded transient program: 

005 OH : Drive that the command file was loaded from 
005 1H : Password address of first file in command tail 
005 3 H : Password length of first file in command tail 
0054H : Password address of second file in command tail 
005 6H : Password length of second file in command tail 
005 CH : Parsed FCB for first file in command tail 
006CH : Parsed FCB for second file in command tail 
00 8 OH : Command tail preceded by command tail length 

Page Zero initialization is covered in more detail in Section 2.4. 

5. At this point, the CCP calls the LOADER module to load the command file 
into the TPA. The LOADER module terminates the load operation if a read 
error occurs, or if the available TPA space is not large enough to contain the 
file. If no RSXs are resident in memory, the available TPA space is deter- 
mined by the address LOADER_base because the LOADER cannot load over 
itself. Otherwise, the maximum TPA address is determined by the base address 
of the lowest RSX in memory. 

6. Once the program is loaded, the LOADER module checks for a RSX header 
on the program. Programs with RSX headers are identified by a return 
instruction at location 100H. 

If an RSX header is present, the LOADER relocates all RSXs attached to the 
end of the program, to the top of the TPA region of memory under the 
LOADER module, or any other RSXs that are already resident. It also updates 
the address in location 0006H of Page Zero to address the lowest RSX in 
memory. Finally, the LOADER discards the RSX header and relocates the 
program file down one page in memory so that the first executable instruc- 
tion resides at 100H. 

7. After initializing Page Zero, the LOADER module sets up a 32-byte stack 
with the return address set to location 0000H of Page Zero and jumps to 
location 100H. At this point, the loaded transient program begins execution. 
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When a transient program terminates execution, the BIOS warm start routine 
reloads the CCP into memory. When the CCP receives control, it tests to see if RSXs 
are resident in memory. If not, it relocates the LOADER module below the BDOS 
module at the top of the TPA region of memory. Otherwise, it skips this step because 
the LOADER module is already resident. The CCP execution cycle then repeats. 

Unlike earlier versions of CP/M, the CCP does not reset the disk system at warm 
start. However, the CCP does reset the disk system if a CTRL-C is typed at the 
prompt. 

1.6.3 Transient Program Operation 

A transient program is one that the CCP loads into the TPA region of memory 
and executes. As the name transient implies, transient programs are not system resi- 
dent. The CCP must load a transient program into memory every time the program 
is to be executed. For example, the utilities PIP and RMAC™ that are shipped with 
CP/M 3 execute as transient programs; programs such as word processing and 
accounting packages distributed by applications vendors also execute as transient 
programs under CP/M 3. 

Section 1.6.2 describes how the CCP prepared the CP/M 3 environment for the 
execution of a transient program. To summarize, the CCP initializes Page Zero to 
contain parsed command-line fields and sets up a 32-byte stack before jumping to 
location 0100H to pass control to the transient program. In addition, the CCP might 
also load RSXs attached to the command file into memory for access by the transient 
program. 

Generally, an executing transient program communicates with the operating sys- 
tem only through BDOS function calls. Transient programs make BDOS function 
calls by loading the CPU registers with the appropriate entry parameters and calling 
location 0005H in Page Zero. 

Transient programs can use BDOS Function 50, Call BIOS, to access BIOS entry 
points. This is the preferred method for accessing the BIOS; however, for compatibil- 
ity with earlier releases of CP/M, transient programs can also make direct BIOS calls 
for console and list I/O by using the jump instruction at location 0000H in Page 
Zero. But, to simplify portability, use direct BIOS calls only where the primitive level 
of functionality provided by the BIOS functions is absolutely required. For example, 
a disk formatting program must bypass CP/M's disk organization to do its job, and 
therefore is justified in making direct BIOS calls. Note however, that disk formatting 
programs are rarely portable. 
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A transient program can terminate execution in one of three ways: by jumping to 
location 0000H, by making a BDOS System Reset call, or by making a BDOS Chain 
To Program call. The first two methods are equivalent; they pass control to the BIOS 
warm start entry point, which then loads the CCP into the TPA, and the CCP 
prompts for the next command. 

The Chain to Program call allows a transient program to specify the next com- 
mand to be executed before it terminates its own execution. A Program Chain call 
executes a standard warm boot sequence, but passes the command specified by the 
terminating program to the CCP in such a way that the CCP executes the specified 
command instead of prompting the console for the next command. 

Transient programs can also set a Program Return Code before terminating by 
making a BDOS Function 108 call, Get/Set Program Return Code. The CCP initial- 
izes the Program Return Code to zero, successful, when it loads a transient program, 
unless the program is loaded as the result of a program chain. Therefore, a transient 
program that terminates successfully can use the Program Return Code to pass a 
value to a chained program. If the program terminates as the result of a BDOS fatal 
error, or a CTRL-C entered at the console, the BDOS sets the return code to an 
unsuccessful value. All other types of program termination leave the return code at 
its current value. 

The CCP has a conditional command facility that uses the Program Return Code. 
If a command line submitted to the CCP by the SUBMIT utility begins with a colon, 
the CCP skips execution of the command if the previous command set an unsuccess- 
ful Program Return Code. In the following example, the SUBMIT utility sends a 
command sequence to the CCP: 

b>SUBMIT SUBFILE 

A > COMPUTE RESUL TS.DAT 

f^>: REPORT RESULTS* DAT 

The CCP does not execute the REPORT command if the COMPUTE command sets 
an unsuccessful Program Return Code. 

1.6.4 Resident System Extension Operation 

This section gives a general overview of RSX use, then describes how RSXs are 
loaded, defines the RSX file structure, and tells how the LOADER module uses the 
RSX prefix and flags to manage RSX activity. 
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A Resident System Extension (RSX) is a special type of program that can be 
attached to the operating system to modify or extend the functionality of the BDOS. 
RSX modules intercept BDOS functions and either perform them, translate them into 
other BDOS functions, or pass them through untouched. The BDOS executes non- 
intercepted functions in the standard manner. 

A transient program can also use BDOS Function 60, Call Resident System Exten- 
sion, to call an RSX for special functions. Function 60 is a general purpose function 
that allows customized interfaces between programs and RSXs. 

Two examples of RSX applications are the GET utility and the LOADER module. 
The GET.COM command file has an attached RSX, GET.RSX, which intercepts all 
console input calls and returns characters from the file specified in the GET command 
line. The LOADER module is another example of an RSX, but it is special because 
it supports Function 59, Load Overlay. It is always resident in memory when other 
RSXs are active. 

RSXs are loaded into memory at program load time. As described in Section 1.6.2, 
after the CCP locates a command file, it calls the LOADER module to load the 
program into the TPA. The LOADER loads the transient program into memory 
along with any attached RSXs. Subsequently, the loader relocates each attached RSX 
to the top of the TPA and adjusts the TPA size by changing the jump at location 
0005H in Page Zero to point to the RSX. When RSX modules reside in memory, the 
LOADER module resides directly below the BDOS, and the RSX modules stack 
downward from it. 

The order in which the RSX modules are stacked affects the order in which they 
intercept BDOS calls. A more recently stacked RSX has precedence over an older 
RSX. Thus, if two RSXs in memory intercept the same BDOS function, the more 
recently loaded RSX handles the function. 

The CP/M 3 utility GENCOM attaches RSX modules to program files. Program 
files with attached RSXs have a special one page header that the LOADER recognizes 
when it loads the command file. GENCOM can also attach one or more RSXs to a 
null command file so that the CCP can load RSXs without having to execute a 
transient program. In this case, the command file consists of the RSX header fol- 
lowed by the RSXs. 

RSX modules are Page Relocatable, PRL, files with the file type RSX. RSX files 
must be page relocatable because their execution address is determined dynamically 
by the LOADER module at load time. RSX files have the following format: 
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END OF FILE: 



0100H: 



0000 H: 



PRLBITMAP 



RSXCODE 



RSX PREFIX 



256 BYTE PRL HEADER 



Figure 1-8. RSX File Format 



RSX files begin with a one page PRL header that specifies the total size of the RSX 
prefix and code sections. The PRL bit map is a string of bits identifying those bytes 
in the RSX prefix and code sections that require relocation. The PRL format is 
described in detail in Appendix B. Note that the PRL header and bit map are removed 
when an RSX is loaded into memory. They are only used by the LOADER module 
to load the RSX. 

The RSX prefix is a standard data structure that the LOADER module uses to 
manage RSXs (see Section 4.4). Included in this data structure are jump instructions 
to the previous and next RSX in memory, and two flags. The LOADER module 
initializes and updates these jump instructions to maintain the link from location 6 
of Page Zero to the BDOS entry point. The RSX flags are the Remove flag and the 
Nonbanked flag. The Remove flag controls RSX removal from memory. The CCP 
tests this flag to determine whether or not it should remove the RSX from memory 
at system warm start. The nonbanked flag identifies RSXs that are loaded only in 
nonbanked CP/M 3 systems. For example, the CP/M 3 RSX, DIRLBL.RSX, is a 
nonbanked RSX. It provides BDOS Function 100, Set Directory Label, support for 
nonbanked systems only. Banked systems support this function in the BDOS. 

The RSX code section contains the main body of the RSX. This section always 
begins with code to intercept the BDOS function that is supported by the RSX. 
Nonintercepted functions are passed to the next RSX in memory. This section can 
also include initialization and termination code that transient programs can call with 
BDOS Function 60. 
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When the CCP gains control after a system warm start, it removes any RSXs in 
memory that have the Remove flag set to OFFH. All other RSXs remain active in 
memory. Setting an RSX's Remove flag to OFFH indicates that the RSX is not active 
and it can be removed. Note that if an RSX marked for removal is not the lowest active 
RSX in memory, it still occupies memory after removal. Although the removed RSX 
cannot be executed, its space is returned to the TPA only when all the lower RSXs are 
removed. 

There is one special case where the CCP does not remove an RSX with the Remove 
flag set to OFFH following warm start. This case occurs on warm starts following the 
load of an empty file with attached RSXs. This exception allows an RSX with the 
Remove flag set to be loaded into memory before a transient program. The transient 
program can then access the RSX during execution. After the transient program 
terminates, however, the CCP removes the RSX from the system environment. 

As an example of RSX operation, here is a description of the operation of the GET 
utility. The GET.COM command file has an attached RSX. The LOADER moves 
this RSX to the top of the TPA when it loads the GET.COM command file. The 
GET utility performs necessary initializations which include opening the ASCII file 
specified in the GET command line. It also makes a BDOS Function 60 call to 
initialize the GET.RSX. At this point, the GET utility terminates. Subsequently, the 
GET. RSX intercepts all console input calls and returns characters from the file speci- 
fied in the GET command line. It continues this action until it reads end-of-file. At 
this point, it sets its Remove flag in the RSX prefix, and stops intercepting console 
input. On the following warm boot, the CCP removes the RSX from memory. 

1.6.5 SUBMIT Operation 

A SUBMIT command line has the following syntax: 

SUBMIT <filespec> <parameters> 

If the CCP identifies a command as a submit file, it automatically inserts the SUBMIT 
keyword into the command line as described in Section 1.6.2. 
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When the SUBMIT utility begins execution, it opens and reads the file specified by 
<filespec> and creates a temporary submit file of type $$$ on the system's tempo- 
rary file drive. GENCPM initializes the temporary file drive to the CCP's current 
default drive. The SETDEF utility can set the temporary file drive to a specific drive. 
As it creates the temporary file, SUBMIT performs the parameter substitutions requested 
by the <parameters> subfield of the SUBMIT command line. See the CP/M Plus 
(CP/M Version 3) Operating System User's Guide for a detailed description of this 
process. 

After SUBMIT creates the temporary submit file, its operation is similar to that of 
the GET utility described in Section 1.6.4. The SUBMIT command file also has an 
attached RSX that performs console input redirection from a file. However, the 
SUBMIT RSX expands upon the simpler facilities provided by the GET RSX. Com- 
mand lines in a submit file can be marked to indicate whether they are program or 
CCP input. Furthermore, if a program exhausts all its program input, the next SUB- 
MIT command is a CCP command, the SUBMIT RSX temporarily reverts to console 
input. Redirected input from the submit file resumes when the program terminates. 

Because CP/M 3's submit facility is implemented with RSXs, submit files can be 
nested. That is, a submit file can contain additional SUBMIT or GET commands. 
Similarly, a GET command can specify a file that contains GET or SUBMIT com- 
mands. For example, when a SUBMIT command is encountered in a submit file, a 
new SUBMIT RSX is created below the current RSX. The new RSX handles console 
input until it reads end-of-file on its temporary submit file. At this point, control 
reverts to the previous SUBMIT RSX. 



1.7 System Control Block 

The System Control Block, SCB, is a 100 byte CP/M 3 data structure that resides 
in the BDOS system component. The SCB contains internal BDOS flags and data, 
CCP flags and data, and other system information such as console characteristics and 
the current date and time. The BDOS, BIOS, CCP system components as well as 
CP/M 3 utilities and RSXs reference SCB fields. BDOS Function 49, Get/Set System 
Control Block, provides access to the SCB fields for transient programs, RSXs, and 
the CCP. 
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However, use caution when you access the SCB through Function 49 for two 
reasons. First, the SCB is a CP/M 3 data structure. Digital Research's multi-user 
operating system, MP/M, does not support BDOS Function 49. Programs that access 
the SCB can run only on CP/M 3. Secondly, the SCB contains critical system param- 
eters that reflect the current state of the operating system. If a program modifies these 
parameters illegally, the operating system might crash. However, for application writ- 
ers who are writing system-oriented applications, access to the SCB variables might 
prove valuable. 

For example, the CCP default drive and current user number are maintained in the 
System Control Block. This information is displayed in the system prompt. If a 
transient program changes the current disk or user number by making an explicit 
BDOS call, the System Control Block values are not changed. They continue to reflect 
the state of the system when the transient program was loaded. For compatibility 
with CP/M Version 2, the current disk and user number are also maintained in 
location 0004H of Page Zero. The high-order nibble contains the user number, and 
the low-order nibble contains the drive. 

Refer to the description of BDOS Function 49 in Section 2.5 for more information 
on the System Control Block. The SCB fields are also discussed in Appendix A. 



End of Section 1 
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Section 2 
The BDOS System Interface 



This section describes the operating system services available to a transient pro- 
gram through the BDOS module of CP/M 3. The section begins by defining how a 
transient program calls BDOS functions, then discusses serial I/O for console, list and 
auxiliary devices, the file system, and Page Zero initialization. 



2.1 BDOS Calling Conventions 

CP/M 3 uses a standard convention for BDOS function calls. On entry to the 
BDOS, register C contains the BDOS function number, and register pair DE contains 
a byte or word value or an information address. BDOS functions return single-byte 
values in register A, and double-byte values in register pair HL. In addition, they 
return with register A equal to L, and register H equal to B. If a transient program 
makes a BDOS call to a nonsupported function number in the range of to 127, the 
BDOS returns with register pair HL set to OFFFFH. For compatibility with MP/M, 
the BDOS returns with register pair HL set to 0000H on nonsupported function 
numbers in the range of 128 to 255. Note that CP/M 2 returns with HL set to zero 
on all invalid function calls. CP/M 3's register passing conventions for BDOS func- 
tion calls are consistent with the conventions used by the Intel PL/M systems pro- 
gramming language. 

When a transient program makes a BDOS function call, the BDOS does not restore 
registers to their entry values before returning to the calling program. The responsi- 
bility for saving and restoring any critical register values rests with the calling program. 

When the CCP loads a transient program, the LOADER module sets the stack 
pointer to a 16 level stack, and then pushes the address 0000H onto the stack. Thus, 
an immediate return to the system is equivalent to a jump to 0000H. However, most 
transient programs set up their own stack, and terminate execution by making a 
BDOS System Reset call (Function 0) or by jumping to location OOOOH. 
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0005 h 
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i 


o r 3 
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call 


bdos 




cpi 


'*' 




Jnz 


n e x t c 




ret 






end 
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The following example illustrates how a transient program calls a BDOS function. 
This program reads characters continuously until it encounters an asterisk. Then it 
terminates execution by returning to the system. 

5 BDOS entry point in Pasfe Zero 
5 BDOS console input function 

5 Base of Transient Program Area 

5 Re turn character in A 
5 End of processing? 
jLoop if not 
^Terminate program 



2.2 BDOS Serial Device I/O 

Under CP/M 3, serial device I/O is simply input to and output from simple devices 
such as consoles, line printers, and communications devices. These physical devices 
can be assigned the logical device names defined below: 

CONIN: logical console input device 

CONOUT: logical console output device 

AUXIN: logical auxiliary input device 

AUXOUT: logical auxiliary output device 

LST: logical list output device 

If your system supports the BIOS DEVTBL function, the CP/M 3 DEVICE utility 
can display and change the assignment of logical devices to physical devices. DEVICE 
can also display the names and attributes of physical devices supported on your 
system. If your system does not support the DEVTBL entry point, then the logical to 
physical device assignments are fixed by the BIOS. 

In general, BDOS serial I/O functions read and write an individual ASCII charac- 
ter, or character string to and from these devices, or test the device's ready status. 
For these BDOS functions, a string of characters is defined as zero to N characters 
terminated by a delimiter. A block of characters is defined as zero to N characters 
where N is specified by a word count field. The maximum value of N in both cases 
is limited only by available memory. The following list summarizes BDOS serial 
device I/O functions. 
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Read a character from CONIN: 

Read a character buffer from CONIN: 

Write a character to CONOUT: 

Write a string of characters to CONOUT: 

Write a block of characters to CONOUT: 

Read a character from AUXIN: 

Write a character to AUXOUT: 

Write a character to LST: 

Write a block of characters to LST: 

Interrogate CONIN:, AUXIN:, AUXOUT: ready 

CP/M 3 cannot run unless CONIN: and CONOUT: are assigned to a physical 
console. The remaining logical devices can remain unassigned. If a logical output 
device is not assigned to a physical device, an output BDOS call to the logical device 
performs no action. If a logical input device is not assigned to a physical device, an 
input BDOS call to the logical device typically returns a CTRL-Z (1AH), which 
indicates end-of-file. Note that these actions depend on your system's BIOS 
implementation. 

2.2.1 BDOS Console I/O 

Because a transient program's main interaction with its user is through the console, 
the BDOS supports many console I/O functions. Console I/O functions can be divided 
into four categories: basic console I/O, direct console I/O, buffered console input, 
and special console functions. Using the basic console I/O functions, programs can 
access the console device for simple input and output. The basic console I/O func- 
tions are: 

1. Console Input - Inputs a single character 

2. Console Output- Outputs a single character 

9. Print String - Outputs a string of characters 
11. Console Status - Signals if a character is ready for input 
111. Print Block - Outputs a block of characters 

The input function echoes the character to the console so that the user can identify 
the typed character. The output functions expand tabs in columns of eight characters. 
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The basic I/O functions also monitor the console to stop and start console output 
scroll at the user's request. To provide this support, the console output functions 
make internal status checks for an input character before writing a character to the 
output device. The console input and console status functions also check the input 
character. If the user types a CTRL-S, these functions make an additional BIOS 
console input call. This input call suspends execution until a character is typed. If the 
typed character is not a CTRL-Q, an additional BIOS console input call is made. 
Execution and console scrolling resume when the user types a CTRL-Q. 

When the BDOS is suspended because of a typed CTRL-S, it scans input for three 
special characters: CTRL-Q, CTRL-C, and CTRL-P. If the user types any other 
character, the BDOS echoes a bell character, CTRL-G, to the console, discards the 
input character, and continues the scan. If the user types a CTRL-C, the BDOS 
executes a warm start which terminates the calling program. If the user types a 
CTRL-P, the BDOS toggles the printer echo switch. The printer echo switch controls 
whether console output is automatically echoed to the list device, LST:. The BDOS 
signals when it turns on printer echo by sending a bell character to the console. 

All basic console I/O functions discard any CTRL-Q or CTRL-P character that is 
not preceded by a CTRL-S character. Thus, BDOS function 1 cannot read a CTRL- 
S, CTRL-Q, or CTRL-P character. Furthermore, these characters are invisible to the 
console status function. 

The second category of console I/O is direct console I/O. BDOS function 6 can 
provide direct console I/O in situations where unadorned console I/O is required. 
Function 6 actually consists of several sub-functions that support direct console input, 
output, and status checks. The BDOS does not filter out special characters during 
direct console I/O. The direct output sub-function does not expand tabs, and the 
direct input sub-function does not echo typed characters to the console. 

The third category of console I/O accepts edited input from the console. The only 
function in this category, Function 10, Read Buffer Input, reads an input line from a 
buffer and recognizes certain control characters that edit the input. As an option, the 
line to be edited can be initialized by the calling program. 

In the nonbanked version of CP/M 3, editing within the buffer is restricted to the 
last character on the line. That is, to edit a character embedded in the line, the user 
must delete all characters that follow the erroneous character, correct the error, and 
then retype the remainder of the line. The banked version of CP/M 3 supports 
complete line editing in which characters can be deleted and inserted anywhere in the 
line. In addition, the banked version can also recall the previously entered line. 
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Function 10 also filters input for certain control characters. If the user types a 
CTRL-C as the first character in the line, Function 10 terminates the calling program 
by branching to the BIOS warm start entry point. A CTRL-C in any other position 
is simply echoed at the console. Function 10 also watches for a CTRL-P keystroke, 
and if it finds one at any position in the command line, it toggles the printer echo 
switch. Function 10 does not filter CTRL-S and CTRL-Q characters, but accepts 
them as normal input. In general, all control characters that Function 10 does not 
recognize as editing control characters, it accepts as input characters. Function 10 
identifies a control character with a leading caret, A , when it echoes the control 
character to the console. Thus, CTRL-C appears as "C in a Function 10 command 
line on the screen. 

The final category of console I/O functions includes special functions that modify 
the behavior of other console functions. These functions are: 

109. Get/Set Console Mode 

110. Get/Set Output Delimiter 

Function 110 can get or set the current delimiter for Function 9, Print String. The 
delimiter is $, when a transient program begins execution. Function 109 gets or sets 
a 16-bit system variable called the Console Mode. The following list describes the 
bits of the Console Mode variable and their functions: 

bit : If this bit is set, Function 11 returns true only if a CTRL-C is typed at the 
console. Programs that make repeated console status calls to test if execution 
should be interrupted, can set this bit to interrupt on CTRL-C only. The 
CCP DIR and TYPE built-in commands run in this mode. 

bit 1 : Setting this bit disables stop and start scroll support for the basic console 
I/O functions, which comprise the first category of functions described in 
this section. When this bit is set, Function 1 reads CTRL-S, CTRL-Q, and 
CTRL-P, and Function 1 1 returns true if the user types these characters. Use 
this mode in situations where raw console input and edited output is needed. 
While in this mode, you can use Function 6 for input and input status, and 
Functions 1, 9, and 111 for output without the possibility of the output 
functions intercepting input CTRL-S, CTRL-Q, or CTRL-P characters. 

bit 2 : Setting this bit disables tab expansion and printer echo support for Functions 
2, 9, and 111. Use this mode when non-edited output is required. 
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bit 3 : This bit disables all CTRL-C intercept action in the BDOS. This mode is 
useful for programs that must control their own termination. 

bits 8 and 9 : The BDOS does not use these bits, but reserves them for the CP/M 3 
GET RSX that performs console input redirection from a file. With one 
exception, these bits determine how the GET RSX responds to a program 
console status request (Function 6, Function 11, or direct BIOS). 

bit 8 = 0, bit 9 = - conditional status 

bit 8 = 0, bit 9 = 1- false status 

bit 8 = 1, bit 9 = - true status 

bit 8 = 1, bit 9 = 1 - do not perform redirection 

In conditional status mode, GET responds false to all status requests except for a 
status call preceded immediately by another status call. On the second call, GET 
responds with a true result. Thus, a program that spins on status to wait for a 
character is signaled that a character is ready on the second call. In addition, a 
program that makes status calls periodically to see if the user wants to stop is not 
signaled. 

When a transient program begins execution, the Console Mode bits are normally 
set to zero. However, the CP/M 3 utility GENCOM can attach an RSX header to a 
COM file so that when it is loaded, the console mode bits are set differently. This 
feature allows you to modify a program's console I/O behavior without having to 
change the program. 

2.2.2 Other Serial I/O 

The BDOS supports single character output functions for the logical devices LST: 
and AUXOUT:, an input function for AUXIN:, and status functions for AUXIN: 
and AUXOUT:. A block output function is also supported for the LST: device. 
Unlike the console I/O functions, the BDOS does not intercept control characters or 
expand tabs for these functions. Note that AUXIN: and AUXOUT: replace the 
READER and PUNCH devices supported by earlier versions of CP/M. 
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2.3 BDOS File System 

Transient programs depend on the BDOS file system to create, update, and main- 
tain disk files. This section describes the capabilities of the BDOS file system in detail. 
You must understand the general features of CP/M 3 described in Section 1 before 
you can use the detail presented in this section. 

The remaining introductory paragraphs define the four categories of BDOS file 
functions. This is followed by a review of file naming conventions and disk and file 
organization. The section then describes the data structure used by the BDOS file, 
and directory oriented functions: the File Control Block (FCB). Subsequent discus- 
sions cover file attributes, user numbers, directory labels and extended File Control 
Blocks (XFCBs), passwords, date and time stamping, blocking and deblocking, multi- 
sector I/O, disk reset and removable media, byte counts, and error handling. These 
topics are closely related to the BDOS file system. You must be familiar with the 
contents of Section 2 before attempting to use the BDOS functions described individ- 
ually in Section 3. 

The BDOS file system supports four categories of functions: file access functions, 
directory functions, drive related functions, and miscellaneous functions. The file 
access category includes functions to create a file, open an existing file, and close a 
file. Both the make and open functions activate the file for subsequent access by 
BDOS file access functions. The BDOS read and write functions are file access func- 
tions that operate either sequentially or randomly by record position. They transfer 
data in units of 128 bytes, which is the basic record size of the file system. The close 
function makes any necessary updates to the directory to permanently record the 
status of an activated file. 
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BDOS directory functions operate on existing file entries in a drive's directory. 
This category includes functions to search for one or more files, delete one or more 
files, truncate a file, rename a file, set file attributes, assign a password to a file, and 
compute the size of a file. The search and delete functions are the only BDOS func- 
tions that support ambiguous file references. All other directory and file related func- 
tions require a specific file reference. 

The BDOS drive-related category includes functions that select the default drive, 
compute a drive's free space, interrogate drive status, and assign a directory label to 
a drive. A drive's directory label controls whether or not CP/M 3 enforces file pass- 
word protection, or stamps files with the date and time. Note that the nonbanked 
version of CP/M 3 does not support file passwords. 

The miscellaneous category includes functions to set the current DMA address, 
access and update the current user number, chain to a new program, and flush 
internal blocking/deblocking buffers. Also included are functions that set the BDOS 
multi-sector count, and the BDOS error mode. The BDOS multi-sector count deter- 
mines the number of 128-byte records to be processed by BDOS read and write 
functions. It can range from 1 to 128. The BDOS error mode determines how the 
BDOS file system handles certain classes of errors. 

Also included in the miscellaneous category are functions that call the BIOS directly, 
set a program return code, and parse filenames. If the LOADER RSX is resident in 
memory, programs can also make a BDOS function call to load an overlay. Another 
miscellaneous function accesses system variables in the System Control Block. 
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The following list summarizes the operations performed by the BDOS file system: 

Disk System Reset 

Drive Selection 

File Creation 

File Open 

File Close 

Directory Search 

File Delete 

File Rename 

Random or Sequential Read 

Random or Sequential Write 

Interrogate Selected Disks 

Set DMA Address 

Set/Reset File Attributes 

Reset Drive 

Set BDOS Multi-Sector Count 

Set BDOS Error Mode 

Get Disk Free Space 

Chain to Program 

Flush Buffers 

Get/Set System Control Block 

Call BIOS 

Load Overlay 

Call RSX 

Truncate File 

Set Directory Label 

Get File's Date Stamps and Password Mode 

Write File XFCB 

Set/Get Date and Time 

Set Default Password 

Return CP/M 3 Serial Number 

Get/Set Program Return Code 

Parse Filename 

2.3.1 File Naming Conventions 

Under CP/M 3, a file specification consists of four parts: the drive specifier, the 
filename field, the filetype field, and the file password field. The general format for a 
command line file specification is shown below: 

{d:}filename{.typK;password} 
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The drive specifier field specifies the drive where the file is located. The filename and 
type fields identify the file. The password field specifies the password if a file is 
password protected. 

The drive, type, and password fields are optional, and the delimiters :.; are required 
only when specifying their associated field. The drive specifier can be assigned a letter 
from A to P where the actual drive letters supported on a given system are deter- 
mined by the BIOS implementation. When the drive letter is not specified, the current 
default drive is assumed. 

The filename and password fields can contain one to eight non-delimiter charac- 
ters. The filetype field can contain one to three non-delimiter characters. All three 
fields are padded with blanks, if necessary. Omitting the optional type or password 
fields implies a field specification of all blanks. 

The CCP calls BDOS Function 152, Parse Filename, to parse file specifications 
from a command line. Function 152 recognizes certain ASCII characters as valid 
delimiters when it parses a file from a command line. The valid delimiters are shown 
in Table 2-1. 



Table 2-1. 


Valid Filename Delimiters 


ASCII 


HEX EQUIVALENT 


null 


00 


space 


20 


return 


0D 


tab 


09 




3A 


. 


2E 


> 


3B 


= 


3D 


j 


2C 


[ 


5B 


] 


5D 


< 


3C 


> 


3E 


1 


7C 
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Function 152 also excludes all control characters from the file fields, and translates all 
lower-case letters to upper-case. 

Avoid using parentheses and the backslash character, \ , in the filename and filetype 
fields because they are commonly used delimiters. Use asterisk and question mark 
characters, * and ?, only to make an ambiguous file reference. When Function 152 
encounters an * in a filename or filetype field, it pads the remainder of the field with 
question marks. For example, a filename of X*.* is parsed to X???????.???. The 
BDOS search and delete functions treat a ? in the filename and type fields as follows: 
A ? in any position matches the corresponding field of any directory entry belonging 
to the current user number. Thus, a search operation for X???????.??? finds all the 
current user files on the directory beginning in X. Most other file related BDOS 
functions treat the presence of a ? in the filename or type field as an error. 

It is not mandatory to follow the file naming conventions of CP/M 3 when you 
create or rename a file with BDOS functions. However, the conventions must be used 
if the file is to be accessed from a command line. For example, the CCP cannot locate 
a command file in the directory if its filename or type field contains a lower-case 
letter. 

As a general rule, the filetype field names the generic category of a particular file, 
while the filename distinguishes individual files in each category. Although they are 
generally arbitrary, the following list of filetypes names some of the generic categories 
that have been established. 



ASM 


Assembler Source 


PLI 


PL/I Source File 


PRN 


Printer Listing 


REL 


Relocatable Module 


HEX 


Hex Machine Code 


TEX 


TEX Formatter Source 


BAS 


Basic Source File 


BAK 


ED Source Backup 


INT 


Intermediate File 


SYM 


SID Symbol File 


COM 


Command File 


$$$ 


Temporary File 


PRL 


Page Relocatable 


DAT 


Data File 


SPR 


Sys. Page Reloc. 


SYS 


System File 



2.3.2 Disk and File Organization 

The BDOS file system can support from one to sixteen logical drives. The maxi- 
mum file size supported on a drive is 32 megabytes. The maximum capacity of a 
drive is determined by the data block size specified for the drive in the BIOS. The 
data block size is the basic unit in which the BDOS allocates disk space to files. 
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Table 2-2 displays the relationship between data block size and drive capacity. 



Table 2-2. Logical Drive Capacity 



Data Block Size 


Maximum Drive Capacity 


IK 


256 Kilobytes 


2K 


64 Megabytes 


4K 


128 Megabytes 


8K 


256 Megabytes 


16K 


512 Megabytes 



Logical drives are divided into two regions: a directory area and a data area. The 
directory area contains from one to sixteen blocks located at the beginning of the 
drive. The actual number is set in the BIOS. This area contains entries that define 
which files exist on the drive. The directory entries corresponding to a particular file 
define those data blocks in the drive's data area that belong to the file. These data 
blocks contain the file's records. The directory area is logically subdivided into six- 
teen independent directories identified as user through 15. Each independent direc- 
tory shares the actual directory area on the drive. However, a file's directory entries 
cannot exist under more than one user number. In general, only files belonging to 
the current user number are visible in the directory. 

Each disk file consists of a set of up to 262,144 128-byte records. Each record in 
a file is identified by its position in the file. This position is called the record's random 
record number. If a file is created sequentially, the first record has a position of zero, 
while the last record has a position one less than the number of records in the file. 
Such a file can be read sequentially in record position order beginning at record zero, 
or randomly by record position. Conversely, if a file is created randomly, records are 
added to the file by specified position. A file created in this way is called sparse if 
positions exist within the file where a record has not been written. 

The BDOS automatically allocates data blocks to a file to contain its records on 
the basis of the record positions consumed. Thus, a sparse file that contains two 
records, one at position zero, the other at position 262,143, consumes only two data 
blocks in the data area. Sparse files can only be created and accessed randomly, not 
sequentially. Note that any data block allocated to a file is permanently allocated to 
the file until the file is deleted or truncated. These are the only mechanisms supported 
by the BDOS for releasing data blocks belonging to a file. 
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Source files under CP/M 3 are treated as a sequence of ASCII characters, where 
each line of the source file is followed by a carriage return line-feed sequence, ODH 
followed by OAH. Thus a single 128 -byte record could contain several lines of source 
text. The end of an ASCII file is denoted by a CTRL-Z character, 1AH, or a real end 
of file, returned by the BDOS read operation. CTRL-Z characters embedded within 
machine code files such as COM files are ignored. The actual end-of-file condition 
returned by the BDOS is used to terminate read operations. 

2.3.3 File Control Block Definition 

The File Control Block, FCB, is a data structure that is set up and initialized by a 
transient program, and then used by any BDOS file access and directory functions 
called by the transient program. Thus the FCB is an important channel for informa- 
tion exchange between the BDOS and a transient program. For example, when a 
program opens a file, and subsequently accesses it with BDOS read and write record 
functions, the BDOS file system maintains the current file state and position within 
the program's FCB. Some BDOS functions use certain fields in the FCB for invoking 
special options. Other BDOS functions use the FCB to return data to the calling 
program. In addition, all BDOS random I/O functions specify the random record 
number with a 3 -byte field at the end of the FCB. 

When a transient program makes a file access or directory BDOS function call, 
register pair DE must address an FCB. The length of the FCB data area depends on 
the BDOS function. For most functions, the required length is 33 bytes. For random 
I/O functions, the Truncate File function, and the Compute File Size function, the 
FCB length must be 36 bytes. The FCB format is shown on the next page. 
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dr 


fl 


f2 




f8 


tl 


t2 


t3 


ex 


si 


s2 


re 


do 




dn 


cr 


rO 


rl 


r2 



00 01 02 

where 

dr 



fl...f8 



tl,t2,t3 



ex 

si 
s2 
re 



08 09 10 11 12 13 14 15 16 



31 32 33 34 35 



drive code (0-16) 

= > use default drive for file 

1 = > auto disk select drive A, 

2 = > auto disk select drive B, 

16 = > auto disk select drive P. 

contain the filename in ASCII 
upper-case, with high bit = 0. 
fl ',..., f8' denote the high- 
order bit of these positions, 
and are file attribute bits. 

contain the filetype in ASCII 

upper-case, with high bit = 0. 

tl', t2', and t3' denote the 

high bit of these positions, 

and are file attribute bits. 

tl' = 1 => Read/Only file 

t2' = 1 = > System file 

t3' = 1 = > File has been archived 

contains the current extent number, 
usually set to by the calling program, 
but can range 0-31 during file I/O 

reserved for internal system use 

reserved for internal system use 

record count for extent "ex" 
takes on values from - 255 
(values greater than 128 imply 
record count equals 128) 
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dCL.dn filled-in by CP/M 3, reserved for 

system use 

cr current record to read or write in 

a sequential file operation, normally 
set to zero by the calling program 
when a file is opened or created 

r0,rl,r2 optional random record number in the 

range 0-262,143 (0 - 3FFFFH). 
ro,rl,r2 constitute a 18 bit value 
with low byte rO, middle byte rl, and 
high byte r2. 



For BDOS directory functions, the calling program must initialize bytes through 
11 of the FCB before issuing the function call. The Set Directory Label and Write 
File XFCB functions also require the calling program to initialize byte 12. The Rename 
File function requires the calling program to place the new filename and type in bytes 
17 through 27. 

BDOS open or make function calls require the calling program to intialize bytes 
through 12 of the FCB before making the call. Usually, byte 12 is set to zero. In 
addition, if the file is to be processed from the beginning using sequential read or 
write functions, byte 32, cr, must be zeroed. 

After an FCB is activated by an open or make operation, a program does not have 
to modify the FCB to perform sequential read or write operations. In fact, bytes 
through 31 of an activated FCB should not be modified. However, random I/O 
functions require that a program set bytes 33 through 35 to the requested random 
record number prior to making the function call. 

File directory entries maintained in the directory area of each disk have the same 
format as FCBs, excluding bytes 32 through 35, except for byte which contains the 
file's user number. Both the Open File and Make File functions bring these entries, 
excluding byte 0, into memory in the FCB specified by the calling program. All read 
and write operations on a file must specify an FCB activated in this manner. 
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The BDOS updates the memory copy of the FCB during file processing to maintain 
the current position within the file. During file write operations, the BDOS updates 
the memory copy of the FCB to record the allocation of data to the file, and at the 
termination of file processing, the Close File function permanently records this infor- 
mation on disk. Note that data allocated to a file during file write operations is not 
completely recorded in the directory until the calling program issues a Close File call. 
Therefore, a program that creates or modifies files must close the files at the end of 
any write processing. Otherwise, data might be lost. 

The BDOS Search and Delete functions support multiple or ambiguous file refer- 
ences. In general, a question mark in the filename, filetype, or extent field matches 
any value in the corresponding positions of directory FCBs during a directory search 
operation. The BDOS search functions also recognize a question mark in the drive 
code field, and if specified, they return all directory entries on the disk regardless of 
user number, including empty entries. A directory FCB that begins with E5H is an 
empty directory entry. 

2.3.4 File Attributes 

The high-order bits of the FCB filename, fl',...,f8', and filetype, tl',t2',t3', fields 
are called attribute bits. Attributes bits are 1 bit Boolean fields where 1 indicates on 
or true, and indicates off or false. Attribute bits indicate two kinds of attributes 
within the file system: file attributes and interface attributes. 

The file attribute bits, fl',...,f4' and tl',t2',t3', can indicate that a file has a defined 
file attribute. These bits are recorded in a file's directory FCBs. File attributes can be 
set or reset only by the BDOS Set File Attributes function. When the BDOS Make 
File function creates a file, it initializes all file attributes to zero. A program can 
interrogate file attributes in an FCB activated by the BDOS Open File function, or in 
directory FCBs returned by the BDOS Search For First and Search For Next functions. 

Note: the BDOS file system ignores file attribute bits when it attempts to locate a file 
in the directory. 

The file system defines the file attribute bits, tl',t2',t3', as follows: 

tl': Read-Only attribute - The file system prevents write operations to a file with 
the read-only attribute set. 
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t2': System attribute - This attribute, if set, identifies the file as a CP/M 3 system 
file. System files are not usually displayed by the CP/M 3 DIR command. In 
addition, user-zero system files can be accessed on a read-only basis from other 
user numbers. 

t3': Archive attribute - This attribute is designed for user written archive programs. 
When an archive program copies a file to backup storage, it sets the archive 
attribute of the copied files. The file system automatically resets the archive 
attribute of a directory FCB that has been issued a write command. The archive 
program can test this attribute in each of the file's directory FCBs via the BDOS 
Search and Search Next functions. If all directory FCBs have the archive attri- 
bute set, it indicates that the file has not been modified since the previous 
archive. Note that the CP/M 3 PIP utility supports file archival. 

Attributes fl' through f4' are available for definition by the user. 

The interface attributes are indicated by bits f5' through f8' and cannot be used as 
file attributes. Interface attributes f5' and f6' can request options for BDOS Make 
File, Close File, Delete File, and Set File Attributes functions. Table 2-3 defines options 
indicated by the f5' and f6' interface attribute bits for these functions. 



Table 2-3. BDOS Interface Attributes 



BDOS Function 


Interface 


Attribute Definition 


16. Close File 


f5' = 1 


. Partial Close 


19. Delete File 


f5' = 1 


: Delete file XFCBs 
only 


22. Make File 


ie = 1 


: Assign password to 
file 


30. Set File Attributes 


f6' = 1 


Set file byte count 



Section 3 discusses each interface attribute in detail in the definitions of the above 
functions. Attributes f5' and f6' are always reset when control is returned to the 
calling program. Interface attributes f7' and f8' are reserved for internal use by the 
BDOS file system. 
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2.3.5 User Number Conventions 

The CP/M 3 User facility divides each drive directory into sixteen logically inde- 
pendent directories, designated as user through user 15. Physically, all user direc- 
tories share the directory area of a drive. In most other aspects, however, they are 
independent. For example, files with the same name can exist on different user num- 
bers of the same drive with no conflict. However, a single file cannot reside under 
more than one user number. 

Only one user number is active for a program at one time, and the current user 
number applies to all drives on the system. Furthermore, the FCB format does not 
contain any field that can be used to override the current user number. As a result, 
all file and directory operations reference directories associated with the current user 
number. However, it is possible for a program to access files on different user num- 
bers; this can be accomplished by setting the user number to the file's user number 
with the BDOS Set User function before making the desired BDOS function call for 
the file. Note that this technique must be used carefully. An error occurs if a program 
attempts to read or write to a file under a user number different from the user 
number that was active when the file was opened. 

When the CCP loads and executes a transient program, it initializes the user num- 
ber to the value displayed in the system prompt. If the system prompt does not 
display a user number, user zero is implied. A transient program can change its user 
number by making a BDOS Set User function call. Changing the user number in this 
way does not affect the CCP's user number displayed in the system prompt. When 
the transient program terminates, the CCP's user number is restored. However, an 
option of the BDOS Program Chain command allows a program to pass its current 
user number and default drive to the chained program. 

User has special properties under CP/M 3. When the current user number is not 
equal to zero, and if a requested file is not present under the current user number, 
the file system automatically attempts to open the file under user zero. If the file 
exists under user zero, and if it has the system attribute, t2', set, the file is opened 
from user zero. Note, however, that files opened in this way cannot be written to; 
they are available only for read access. This procedure allows utilities that may 
include overlays and any other commonly accessed files to be placed on user zero, 
but also be available for access from other user numbers. As a result, commonly 
needed utilities need not be copied to all user numbers on a directory, and you can 
control which user zero files are directly accessible from other user numbers. 
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2.3.6 Directory Labels and XFCBs 

The BDOS file system includes two special types of FCBs: the XFCB and the 
Directory Label. The XFCB is an extended FCB that optionally can be associated 
with a file in the directory. If present, it contains the file's password. Note that 
password protected files and XFCBs are supported only in the banked version of 
CP/M 3. The format of the XFCB follows. 



DR 


FILE 


TYPE 


PM 


S1 


S2 


RC 


PASSWORD 


RESERVED 


00 01 . . . 


09 . . 


12 13 14 15 


16 


24 



Figure 2-1. XFCB Format 



dr 
file 
type 
pm 



sl,s2,rc 

password 

reserved 



drive code (0-16) 

filename field 

filetype field 

password mode 

bit 7 - Read mode 

bit 6 - Write mode 

bit 5 - Delete mode 

* * - bit references are right to left, 

relative to 
reserved for system use 
8-byte password field (encrypted) 
8-byte reserved area 
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An XFCB can be created only on a drive that has a directory label, and only if the 
directory label has activated password protection. For drives in this state, an XFCB 
can be created for a file in two ways: by the BDOS Make function or by the BDOS 
Write File XFCB function. The BDOS Make function creates an XFCB if the calling 
program requests that a password be assigned to the created file. The BDOS Write 
File XFCB function can be used to assign a password to an existing file. Note that in 
the directory, an XFCB is identified by a drive byte value, byte in the FCB, equal 
to 16 + N, where N equals the user number. 

For its drive, the directory label specifies if file password support is to be activated, 
and if date and time stamping for files is to be performed. The format of the Direc- 
tory Label follows. 



DR 


NAME 


TYPE 


D1 


S1 


S2 


RC 


PASSWORD 


TS1 


TS2 


00 


01 . . 


09 . . 


12 13 14 15 


16 


24 . 


28 . 



Figure 2-2. Directory Label Format 



dr 


drive code (0 - 16) 


name 


Directory Label name 


type 


Directory Label type 


dl 


Directory Label data byte 




bit 7 - require passwords for password 




protected files 




bit 6 - perform access time stamping 




bit 5 - perform update time stamping 




bit 4 - perform create time stamping 




bit - Directory Label exists 




* * - bit references are right to left, 




relative to 


sl,s2,rc 


n/a 


password - 


8-byte password field (encrypted) 


tsl 


4-byte creation time stamp field 


ts2 


4-byte update time stamp field 
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Only one Directory Label can exist in a drive's directory. The Directory Label name 
and type fields are not used to search for a Directory Label; they can be used to 
identify a disk. A Directory Label can be created, or its fields can be updated by 
BDOS function 100, Set Directory Label. This function can also assign a Directory 
Label a password. The Directory Label password, if assigned, cannot be circum- 
vented, whereas file password protection is an option controlled by the Directory 
Label. Thus, access to the Directory Label password provides a kind of super-user 
status on that drive. 

The nonbanked version of CP/M 3 does not support file passwords. However, it 
does provide password protection of directory labels. The CP/M 3 RSX, DIRLBL.RSX, 
which implements BDOS Function 100 in the nonbanked version of CP/M 3, pro- 
vides this support. 

The BDOS file system has no function to read the Directory Label FCB directly. 
However, the Directory Label data byte can be read directly with the BDOS Function 
101, Return Directory Label. In addition, the BDOS Search functions, with a ? in the 
FCB drive byte, can be used to find the Directory Label on the default drive. In the 
directory, the Directory Label is identified by a drive byte value, byte in the FCB, 
equal to 32, 20H. 

2.3.7 File Passwords 

Only the banked version of CP/M 3 supports file passwords. In the nonbanked 
version, all BDOS functions with password related options operate the same way the 
banked version does when passwords are not enabled. 

Files can be assigned passwords in two ways: by the Make File function or by the 
Write File XFCB function. A file's password can also be changed by the Write File 
XFCB function if the original password is supplied. 

Password protection is provided in one of three modes. Table 2-4 shows the differ- 
ence in access level allowed to BDOS functions when the password is not supplied. 
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Table 2-4. Password Protection Modes 



Password 
Mode 


Access level allowed when the password 
is not supplied. 


1. Read 


The file cannot be read. 


2. Write 


The file can be read, but not modified. 


3. Delete 


The file can be modified, but not 
deleted. 



If a file is password protected in Read mode, the password must be supplied to open 
the file. A file protected in Write mode cannot be written to without the password. 
A file protected in Delete mode allows read and write access, but the user must 
specify the password to delete the file, rename the file, or to modify the file's attri- 
butes. Thus, password protection in mode 1 implies mode 2 and 3 protection, and 
mode 2 protection implies mode 3 protection. All three modes require the user to 
specify the password to delete the file, rename the file, or to modify the file's attributes. 

If the correct password is supplied, or if password protection is disabled by the 
Directory Label, then access to the BDOS functions is the same as for a file that is 
not password protected. In addition, the Search For First and Search For Next func- 
tions are not affected by file passwords. 

Table 2-5 lists the BDOS functions that test for password. 



Table 2-5. BDOS Functions That Test For Password 



15. 


Open File 


19. 


Delete File 


23. 


Rename File 


30. 


Set File Attributes 


99. 


Truncate File 


100. 


Set Directory Label 


103. 


Write File XFCB 
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File passwords are eight bytes in length. They are maintained in the XFCB Direc- 
tory Label in encrypted form. To make a BDOS function call for a file that requires 
a password, a program must place the password in the first eight bytes of the current 
DMA, or specify it with the BDOS function, Set Default Password, prior to making 
the function call. 

Note: the BDOS keeps an assigned default password value until it is replaced with a 
new assigned value. 

2.3.8 File Date and Time Stamps 

The CP/M 3 File System uses a special type of directory entry called an SFCB to 
record date and time stamps for files. When a directory has been initialized for date 
and time stamping, SFCBs reside in every fourth position of the directory. Each SFCB 
maintains the date and time stamps for the previous three directory entries as shown 
in Figure 2-3. 





FCB 1 




FCB2 




FCB 3 


21 


STAMPS FOR 
FCB1 


STAMPS FOR 
FCB 2 


STAMPS FOR 
FCB 3 


1 



Figure 2-3. Directory Record with SFCB 



This figure shows a directory record that contains an SFCB. Directory records consist 
of four directory entries, each 32 bytes long. SFCBs always occupy the last position 
of a directory record. 

The SFCB directory item contains five fields. The first field is one byte long and 
contains the value 21H. This value identifies the SFCB in the directory. The next 
three fields, the SFCB subfields, contain the date and time stamps for their corre- 
sponding FCB entries in the directory record. These fields are 10 bytes long. The last 
byte of the SFCB is reserved for system use. The format of the SFCB subfields is 
shown in Table 2-6. 
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Table 2-6. SFCB Subfields Format 



Offset in Bytes 



SFCB Subfield Contents 



Create or Access Date and Time Stamp field 
Update Date and Time Stamp field 
Password mode field 
Reserved 



An SFCB subfield contains valid information only if its corresponding FCB in the 
directory record is an extent zero FCB. This FCB is a file's first directory entry. For 
password protected files, the SFCB subfield also contains the password mode of the 
file. This field is zero for files that are not password protected. The BDOS Search and 
Search Next functions can be used to access SFCBs directly. In addition, BDOS 
Function 102 can return the file date and time stamps and password mode for a 
specified file. Refer to Section 3, function 102, for a description of the format of a 
date and time stamp field. 

CP/M 3 supports three types of file stamping: create, access, and update. Create 
stamps record when the file was created, access stamps record when the file was last 
opened, and update stamps record the last time the file was modified. Create and 
access stamps share the same field. As a result, file access stamps overwrite any create 
stamps. 

The CP/M 3 utility, INITDIR, initializes a directory for date and time stamping by 
placing SFCBs in every fourth directory entry. Date and time stamping is not sup- 
ported on disks that have not been initialized in this manner. For initialized disks the 
disks' Directory Label determines the type of date and time stamping supported for 
files on the drive. If a disk does not have a Directory Label, or if it is Read-Only, or 
if the disk's Directory Label does not specify date and time stamping, then date and 
time stamping for files is not performed. Note that the Directory Label is also time 
stamped, but these stamps are not made in an SFCB. Time stamp fields in the last 
eight bytes of the Directory Label record when it was created and last updated. 
Access stamping for Directory Labels is not supported. 
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The BDOS file system uses the CP/M 3 system date and time when it records a 
date and time stamp. This value is maintained in a field in the System Control Block 
(SCB). On CP/M 3 systems that support a hardware clock, the BIOS module directly 
updates the SCB system date and time field. Otherwise, date and time stamps record 
the last initialized value for the system date and time. The CP/M 3 DATE utility can 
be used to set the system date and time. 

2.3.9 Record Blocking and Deblocking 

Under CP/M 3, the logical record size for disk I/O is 128 bytes. This is the basic 
unit of data transfer between the operating system and transient programs. However, 
on disk, the record size is not restricted to 128 bytes. These records, called physical 
records, can range from 128 bytes to 4K bytes in size. Record blocking and deblock- 
ing is required on systems that support drives with physical record sizes larger than 
128 bytes. 

The process of building up physical records from 128 byte logical records is called 
record blocking. This process is required in write operations. The reverse process of 
breaking up physical records into their component 128 byte logical records is called 
record deblocking. This process is required in read operations. Under CP/M 3, record 
blocking and deblocking is normally performed by the BDOS. 

Record deblocking implies a read-ahead operation. For example, if a transient 
program makes a BDOS function call to read a logical record that resides at the 
beginning of a physical record, the entire physical record is read into an internal 
buffer. Subsequent BDOS read calls for the remaining logical records access the 
buffer instead of the disk. Conversely, record blocking results in the postponement 
of physical write operations but only for data write operations. For example, if a 
transient program makes a BDOS write call, the logical record is placed in a buffer 
equal in size to the physical record size. The write operation on the physical record 
buffer is postponed until the buffer is needed in another I/O operation. Note that 
under CP/M 3, directory write operations are never postponed. 

Postponing physical record write operations has implications for some applications 
programs. For those programs that involve file updating, it is often critical to guar- 
antee that the state of the file on disk parallels the state of the file in memory after 
the update operation. This is only an issue on systems where physical write opera- 
tions are postponed because of record blocking and deblocking. If the system should 
crash while a physical buffer is pending, data would be lost. To prevent this loss of 
data, the BDOS Flush Buffers function, function 48, can be called to force the write 
of any pending physical buffers. 
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Note: the CCP automatically discards all pending physical data buffers when it 
receives control following a system warm start. However, the BDOS file system 
automatically makes a Flush Buffers call in the Close File function. Thus, it is suffi- 
cient to close a file to ensure that all pending physical buffers for that file are written 
to the disk. 

2.3.10 Multi-Sector I/O 

CP/M 3 can read or write multiple 128-byte records in a single BDOS function 
call. This process, called multi-sector I/O, is useful primarily in sequential read and 
write operations, particularly on drives with physical record sizes larger than 128 
bytes. In a multi-sector I/O operation, the BDOS file system bypasses, when possible, 
all intermediate record buffering. Data is transferred directly between the TPA and 
the drive. In addition, the BDOS informs the BIOS when it is reading or writing 
multiple physical records in sequence on a drive. The BIOS can use this information 
to further optimize the I/O operation resulting in even better performance. Thus, the 
primary objective of multi-sector I/O is to improve sequential I/O performance. The 
actual improvement obtained, however, depends on the hardware environment of the 
host system, and the implementation of the BIOS. 

The number of records that can be supported with multi-sector I/O ranges from 1 
to 128. This value can be set by BDOS function 44, Set multi-sector Count. The 
multi-sector count is set to one when a transient program begins execution. However, 
the CP/M 3 LOADER module executes with the multi-sector Count set to 128 unless 
the available TPA space is less than 16K. In addition, the CP/M 3 PIP utility also 
sets the multi-sector count to 128 when sufficient buffer space is available. Note that 
the greatest potential performance increases are obtained when the multi-sector count 
is set to 128. Of course, this requires a 16K buffer. 

The multi-sector count determines the number of operations to be performed by 
the following BDOS functions: 

■ Sequential Read and Write functions 

■ Random Read and Write functions including Write Random with Zero Fill 

If the multi-sector count is N, calling one of the above functions is equivalent to 
making N function calls. If a multi-sector I/O operation is interrupted with an error 
such as reading unwritten data, the file system returns in register H the number of 
128-byte records successfully processed. 



] DIGITAL RESEARCH 7 



2-26 



CP/M 3 Programmer's Guide 2.3 BDOS File System 



2.3.11 Disk Reset and Removable Media 

The BDOS functions, Disk Reset (function 13) and Reset Drive (function 37) allow 
a program to control when a disk's directory is to be reinitialized for file operations. 
This process of initializing a disk's directory is called logging-in the drive. When 
CP/M 3 is cold started, all drives are in the reset state. Subsequently, as drives are 
referenced, they are automatically logged-in by the file system. Once logged-in, a 
drive remains in the logged-in state until it is reset by BDOS function 13 or 37. 
Following the reset operation, the drive is again automatically logged-in by the file 
system when it is next used. Note that BDOS functions 13 and 37 have similar effects 
except that function 13 is directed to all drives on the system. Any combination of 
drives can be reset with Function 37. 

Logging-in a drive consists of several steps. The most important step is the initiali- 
zation of the drive's allocation vector. The allocation vector records the allocation 
and deallocation of data blocks to files, as files are created, extended, deleted, and 
truncated. Another function performed during drive log-in is the initialization of the 
directory check-sum vector. The file system uses the check-sum vector to detect media 
changes on a drive. Note that permanent drives, which are drives that do not support 
media changes, might not have check-sum vectors. If directory hashing has been 
specified for the drive, a BIOS and GENCPM option, the file system creates a hash 
table for the directory during log-in. 

The primary use of the drive reset functions is to prepare for a media change on a 
drive. Subsequently, when the drive is accessed by a BDOS function call, the drive is 
automatically logged-in. Resetting a drive has two important side effects. First of all, 
any pending blocking/deblocking buffers on the reset drive are discarded. Secondly, 
any data blocks that have been allocated to files that have not been closed are lost. 
An application program should close files, particularly files that have been written to, 
prior to resetting a drive. 

Although CP/M 3 automatically relogs in removable media when media changes 
are detected, the application program should still explicitly reset a drive before 
prompting the user to change disks. 
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2.3.12 File Byte Counts 

Although the logical record size of CP/M 3 is restricted to 128 bytes, CP/M 3 does 
provide a mechanism to store and retrieve a byte count for a file. This facility can 
identify the last byte of the last record of a file. The BDOS Compute File Size 
function returns the random record number, plus 1, of the last record of a file. 

The BDOS Set File Attributes function can set a file's byte count. Conversely, the 
Open function can return a file's byte count to the cr field of the FCB. The BDOS 
Search and Search Next functions also return a file's byte count. These functions 
return the byte count in the si field of the FCB returned in the current DMA buffer 
(see BDOS Functions Returned 17 and 26). 

Note that the file system does not access or update the byte count value in file read 
or write operations. However, the BDOS Make File function does set the byte count 
of a file to zero when it creates a file in the directory. 

2.3.13 BDOS Error Handling 

The BDOS file system responds to error situations in one of three ways: 

Method 1. It returns to the calling program with return codes in register 

A, H, and L identifying the error. 

Method 2. It displays an error message on the console, and branches to 

the BIOS warm start entry point, thereby terminating execu- 
tion of the calling program. 

Method 3. It displays an error message on the console, and returns to 

the calling program as in method 1 . 

The file system handles the majority of errors it detects by method 1. Two examples 
of this kind of error are the file not found error for the open function and the reading 
unwritten data error for a read function. More serious errors, such as disk I/O errors, 
are usually handled by method 2. Errors in this category, called physical and extended 
errors, can also be reported by methods 1 and 3 under program control. 
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The BDOS Error Mode, which can exist in three states, determines how the file 
system handles physical and extended errors. In the default state, the BDOS displays 
the error message, and terminates the calling program, method 2. In return error 
mode, the BDOS returns control to the calling program with the error identified in 
registers A, H, and L, method 1. In return and display mode, the BDOS returns 
control to the calling program with the error identified in registers A, H, and L, and 
also displays the error message at the console, method 3. While both return modes 
protect a program from termination because of a physical or extended error, the 
return and display mode also allows the calling program to take advantage of the 
built-in error reporting of the BDOS file system. Physical and extended errors are 
displayed on the console in the following format: 

CP/M Error on d: error message 

BDOS function = nn File = filename.typ 

where d identifies the drive selected when the error condition is detected; error mes- 
sage identifies the error; nn is the BDOS function number, and filename.typ identifies 
the file specified by the BDOS function. If the BDOS function did not involve an 
FCB, the file information is omitted. Note that the second line of the above error 
message is displayed only in the banked version of CP/M 3 if expanded error message 
reporting is requested in GENCPM. It is not displayed in the nonbanked version of 
CP/M 3. 

The BDOS physical errors are identified by the following error messages: 

■ Disk I/O 

■ Invalid Drive 

■ Read-Only File 

■ Read-Only Disk 

The Disk I/O error results from an error condition returned to the BDOS from the 
BIOS module. The file system makes BIOS read and write calls to execute file-related 
BDOS calls. If the BIOS read or write routine detects an error, it returns an error 
code to the BDOS resulting in this error. 

The Invalid Drive error also results from an error condition returned to the BDOS 
from the BIOS module. The BDOS makes a BIOS Select Disk call prior to accessing 
a drive to perform a requested BDOS function. If the BIOS does not support the 
selected disk, the BDOS returns an error code resulting in this error message. 
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The Read-Only File error is returned when a program attempts to write to a file 
that is marked with the Read-Only attribute. It is also returned to a program that 
attempts to write to a system file opened under user zero from a nonzero user 
number. In addition, this error is returned when a program attempts to write to a 
file password protected in Write mode if the program does not supply the correct 
password. 

The Read-Only Disk error is returned when a program writes to a disk that is in 
read-only status. A drive can be placed in read-only status explicitly with the BDOS 
Write Protect Disk function. 

The BDOS extended errors are identified by the following error messages: 

■ Password Error 

■ File Exists 

■ ? in Filename 

The File Password error is returned when the file password is not supplied, or 
when it is incorrect. This error is reported only by the banked version of CP/M 3. 

The File Exists error is returned by the BDOS Make File and Rename File func- 
tions when the BDOS detects a conflict such as a duplicate filename and type. 

The ? in Filename error is returned when the BDOS detects a ? in the filename or 
type field of the passed FCB for the BDOS Rename File, Set File Attributes, Open 
File, Make File, and Truncate File functions. 

The following paragraphs describe the error return code conventions of the BDOS 
file system functions. Most BDOS file system functions fall into three categories in 
regard to return codes: they return an Error Code, a Directory Code, or an Error 
Flag. The error conventions of CP/M 3 are designed to allow programs written for 
earlier versions of CP/M to run without modification. 

The following BDOS functions return an Error Code in register A. 

20. Read Sequential 

21. Write Sequential 

33. Read Random 

34. Write Random 

40. Write Random w/Zero Fill 
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The Error Code definitions for register A are shown in Table 2-7. 



Table 2-7. Register A BDOS Error Codes 



Code 



Meaning 



00 

255 

01 

02 
03 
04 
05 
06 
09 

10 



Function successful 

Physical error : refer to register H 

Reading unwritten data or no available directory space (Write 

Sequential) 

No available data block 

Cannot close current extent 

Seek to unwritten extent 

No available directory space 

Random record number out of range 

Invalid FCB (previous BDOS close call returned an error code 

and invalidated the FCB) 

Media Changed (A media change was detected on the FCB's 

drive after the FCB was opened) 



For BDOS read or write functions, the file system also sets register H when the 
returned Error Code is a value other than zero or 255. In this case, register H 
contains the number of 128-byte records successfully read or written before the error 
was encountered. Note that register H can contain only a nonzero value if the calling 
program has set the BDOS Multi-Sector Count to a value other than one; otherwise 
register H is set to zero. On successful functions, Error Code = 0, register H is also 
set to zero. If the Error Code equals 255, register H contains a physical error code 
(see Table 2-11). 
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The following BDOS functions return a Directory Code in register A: 

15. Open File 

16. Close File 

17. Search For First 

18. Search For Next 

19. Delete File 

22. Make File 

23. Rename File 

30. Set File Attributes 
35. Compute File Size 
99. Truncate File 

* 100. Set Directory Label 

102. Read File Date Stamps and Password Mode 
** 103. Write File XFCB 

* - This function is supported in the DIRLBL.RSX in the nonbanked version of 

CP/M 3. 
** - This function is supported only in the banked version of CP/M 3. 

The Directory Code definitions for register A are shown in Table 2-8. 
Table 2-8. BDOS Directory Codes 



Code 



Meaning 



00 — 03 : successful function 

255 : unsuccessful function 



With the exception of the BDOS search functions, all functions in this category 
return with the directory code set to zero on successful returns. However, for the 
search functions, a successful Directory Code also identifies the relative starting posi- 
tion of the directory entry in the calling program's current DMA buffer. 
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If the Set BDOS Error Mode function is used to place the BDOS in return error 
mode, the following functions return an Error Flag on physical errors: 

14. Select Disk 
46. Get Disk Free Space 
48. Flush Buffers 
98. Free Blocks 
101. Return Directory Label Data 

The Error Flag definition for register A is shown in Table 2-9. 



Table 2-9. BDOS Error Flags 



Code 



Meaning 



00 : successful function 

255 : physical error : refer to register H 



The BDOS returns nonzero values in register H to identify a physical or extended 
error if the BDOS Error Mode is in one of the return modes. Except for functions 
that return a Directory Code, register A equal to 255 indicates that register H iden- 
tifies the physical or extended error. For functions that return a Directory Code, if 
register A equals 255, and register H is not equal to zero, register H identifies the 
physical or extended error. Table 2-10 shows the physical and extended error codes 
returned in register H. 
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Table 2-10. BDOS Physical and Extended Errors 



Code 


Meaning 


00 — 


no error, or not a register H error 


01 — 


Disk I/O error 


02 — 


Read-Only Disk 


03 — 


Read-Only File or File Opened 




under user zero from another user 




number or file password protected 




in write mode and correct pass- 




word not specified. 


04 — 


Invalid Drive : drive select error 


07 — 


Password Error 


08 — 


File Exists 


09 — 


? in Filename 



The following two functions represent a special case because they return an address 
in registers H and L. 

27. Get Addr(Alloc) 

31. Get Addr(Disk Parms) 

When the BDOS is in return error mode, and it detects a physical error for these 
functions, it returns to the calling program with registers A, H, and L all set to 255. 
Otherwise, they return no error code. 



2.4 Page Zero Initialization 

Page Zero is the region of memory located from 0000H to 00FFH. This region 
contains several segments of code and data that are used by transient programs while 
running under CP/M 3. The code and data areas are shown in Table 2-11 for reference. 
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Table 2-11. Page Zero Areas 



Location 


Contents 


From 


To 




0000H — 


0002H 


Contains a jump instruction to the BIOS warm start entry 
point at BIOS_base + 3. The address at location 000 1H can 
also be used to make direct BIOS calls to the BIOS console 
status, console input, console output, and list output primitive 
functions. 


0003H — 


0004H 


(Reserved) 


0005H — 


0007H 


Contains a jump instruction to the BDOS, the LOADER, or 
to the most recently added RSX, and serves two purposes: 
JMP 0005H provides the primary entry point to the BDOS, 
and LHLD 0006H places the address field of the jump 
instruction in the HL register pair. This value, minus one, is 
the highest address of memory available to the transient 
program. 


0008H — 


003AH Reserved interrupt locations for Restarts 1-7 


003BH — 


004FH 


(Not currently used - reserved) 


0050H 




Identifies the drive from which the transient program was load- 
ed. A value of one to sixteen identifies drives A through P. 


005 1H — 


0052H 


Contains the address of the password field of the first command- 
tail operand in the default DMA buffer beginning at 0080H. 
The CCP sets this field to zero if no password for the first 
command-tail operand is specified. 


0053H 




Contains the length of the password field for the first command- 
tail operand. The CCP also sets this field to zero if no password 
for the first command tail is specified. 


0054H — 


0055H 


Contains the address of the password field of the second com- 
mand-tail operand in the default DMA buffer beginning at 
0080H. The CCP sets this field to zero if no password for the 
second command-tail operand is specified. 
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Table 2-11. (continued) 



Location 


Contents 


From 
0056H 


To 

Contains the length of the password field for the second com- 
mand-tail operand. The CCP also sets this field to zero if no 
password for the second command tail is specified. 


0057H — 


005BH (Not currently used - reserved) 


005CH — 


007BH Default File Control Block, FCB, area 1 initialized by the CCP 
from the first command-tail operand of the command line, if 
it exists. 


006CH — 


007BH Default File Control Block, FCB, area 2 initialized by the CCP 
from the second command-tail operand of the command line, 
if it exists. 




Note: this area overlays the last 16 bytes of default FCB 
area 1 . To use the information in this area, a transient program 
must copy it to another location before using FCB area 1. 


007CH 


Current record position of default FCB area 1. This field is used 
with default FCB area 1 in sequential record processing. 


007DH — 


007FH Optional default random record position. This field is an exten- 
sion of default FCB area 1 used in random record processing. 


0080H — 


OOFFH Default 128-byte disk buffer. This buffer is also filled with the 
command tail when the CCP loads a transient program. 
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The CCP initializes Page Zero prior to initiating a transient program. The fields at 
005 OH and above are initialized from the command line invoking the transient pro- 
gram. The command line format was described in detail in Section 1.6.2. To sum- 
marize, a command line usually takes the form: 

<command> <command tail> 

where 

<command> = > <file spec> 

<command tail> = > (no command tail) 
= > <file spec> 
= > <file specXdelimiterXfile spec> 

<file spec> = > {d:}filename{.type} {;password} 

The CCP initializes the command drive field at 005 OH to the drive index, A = 1, ..., 
P = 16, of the drive from which the transient program was loaded. 

The default FCB at 005 CH is defined if a command tail is entered. Otherwise, the 
fields at 005CH, 0068H to 006BH are set to binary zeros, the fields from 005DH to 
0067H are set to blanks. The fields at 005 1H through 0053H are set if a password 
is specified for the first <file spec> of the command tail. If not, these fields are set to 
zero. 

The default FCB at 006CH is defined if a second <file spec> exists in the com- 
mand tail. Otherwise, the fields at 006CH, 0078H to 007BH are set to binary zeros, 
the fields from 005DH to 0067H are set to blanks. The fields at 0054H through 
005 6H are set if a password is specified for the second <file spec> of the command 
tail. If not, these fields are set to zero. 

Transient programs often use the default FCB at 005 CH for file operations. This 
FCB may even be used for random file access because the three bytes starting at 
007DH are available for this purpose. However, a transient program must copy the 
contents of the default FCB at 006CH to another area before using the default FCB 
at 005CH, because an open operation for the default FCB at 005CH overwrites the 
FCB data at 006CH. 
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The default DMA address for transient programs is 00 8 OH. The CCP also initial- 
izes this area to contain the command tail of the command line. The first position 
contains the number of characters in the command line, followed by the command 
line characters. The character following the last command tail character is set to 
binary zero. The command line characters are preceded by a leading blank and are 
translated to ASCII upper-case. Because the 128-byte region beginning at 0080H is 
the default DMA, the BDOS file system moves 128-byte records to this area with 
read operations and accesses 128-byte records from this area with write operations. 
The transient program must extract the command tail information from this buffer 
before performing file operations unless it explicitly changes the DMA address with 
the BDOS Set DMA Address function. 

The Page Zero fields of 005 1H through 0056H locate the password fields of the 
first two file specifications in the command tail if they exist. These fields are provided 
so that transient programs are not required to parse the command tail for password 
fields. However, the transient program must save the password, or change the DMA 
address before performing file operations. 

The following example illustrates the initialization of the command line fields of 
Page Zero. Assuming the following command line is typed at the console: 

D > ft: PROGRAM B: FILE* TYPE? PASS CIFILE, TYPE", PASSWORD 

A hexadecimal dump of 005 OH to 00A5H would show the Page Zero initialization 
performed by the CCP. 

0050H: 01 8D 00 04 9D 00 08 00 00 00 00 00 02 46 49 4C FIL 

00B0H: 45 20 20 20 20 54 59 50 00 00 00 00 03 46 49 4C E....TYP FIL 

0070H: 45 20 20 20 20 54 59 50 00 00 00 00 00 00 00 00 E....TYP 

0080H: 24 20 42 3A 46 49 4C 45 2E 54 59 50 3B 50 41 53 . BrFILE .TYP 5PAS 

0090H: 53 20 43 3A 46 49 4C 45 2E 54 59 50 \3B 50 41 53 8 C:FILE.TYP 5PA5 

00A0H: 53 57 4F 52 44 00 5W0RD. 



End of Section 2 
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Section 3 
BDOS Function Calls 



This section describes each CP/M 3 system function, including the parameters a 
program must pass when calling the function, and the values the function returns to 
the program. The functions are arranged numerically for easy reference. You should 
be familiar with the BDOS calling conventions and other concepts presented in Section 2 
before referencing this section. 



BDOS FUNCTION 0: SYSTEM RESET 



Entry Parameters: 

Register C: 00H 



The System Reset function terminates the calling program and returns control to 
the CCP via a warm start sequence (see Section 1.3.2). Calling this function has the 
same effect as a jump to location 0000H of Page Zero. 

Note that the disk subsystem is not reset by System Reset under CP/M 3. The 
calling program can pass a return code to the CCP by calling Function 108, Get/Set 
Program Return Code, prior to making a System Reset call or jumping to location 
0000H. 
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BDOS FUNCTION 1: 


CONSOLE INPUT 


Entry Parameters: 
Register C: 

Returned Value: 

Register A: 


01H 

ASCII Character 



The Console Input function reads the next character from the logical console, 
CONIN:, to register A. Graphic characters, along with carriage return, line-feed, and 
backspace, CTRL-H, are echoed to the console. Tab characters, CTRL-I, are expanded 
in columns of 8 characters. CTRL-S, CTRL-Q, and CTRL-P are normally intercepted 
as described below. All other non-graphic characters are returned in register A but 
are not echoed to the console. 

When the Console Mode is in the default state (see Section 2.2.1), Function 1 
intercepts the stop scroll, CTRL-S, start scroll, CTRL-Q, and start/stop printer echo, 
CTRL-P, characters. Any characters that are typed following a CTRL-S and preced- 
ing a CTRL-Q are also intercepted. However, if start/stop scroll has been disabled 
by the Console Mode, the CTRL-S, CTRL-Q, and CTRL-P characters are not inter- 
cepted. Instead, they are returned in register A, but are not echoed to the console. 

If printer echo has been invoked, all characters that are echoed to the console are 
also sent to the list device, LST: . 

Function 1 does not return control to the calling program until a non-intercepted 
character is typed, thus suspending execution if a character is not ready. 
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3 BDOS Calls: Function 2 



BDOS FUNCTION 2: CONSOLE OUTPUT 



Entry Parameters: 
Registers C: 
E: 



02H 

ASCII Character 



The Console Output function sends the ASCII character from register E to the 
logical console device, CONOUT:. When the Console Mode is in the default state 
(see Section 2.2.1), Function 2 expands tab characters, CTRL-I, in columns of 8 
characters, checks for stop scroll, CTRL-S, start scroll, CTRL-Q, and echoes charac- 
ters to the logical list device, LST:, if printer echo, CTRL-P, has been invoked. 
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BDOS FUNCTION 3: AUXILIARY INPUT 



Entry Parameters: 

Register C: 03H 

Returned Value: 

Register A: ASCII Character 



The Auxiliary Input function reads the next character from the logical auxiliary 
input device, AUXIN:, into register A. Control does not return to the calling program 
until the character is read. 
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BDOS FUNCTION 4: AUXILIARY OUTPUT 



Entry Parameters: 

Registers C: 04H 

E: ASCII Character 



The Auxiliary Output function sends the ASCII character from register E to the 
logical auxiliary output device, AUXOUT:. 
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BDOS FUNCTION 5: LIST OUTPUT 



Entry Parameters: 

Registers C: 05H 

E: ASCII Character 



The List Output function sends the ASCII character in register E to the logical list 
device, LST:. 
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BDOS FUNCTION 6: 


DIRECT CONSOLE I/O 


Entry Parameters: 






Registers C: 


06H 




E: 


OFFH 


(input/status) or 
OFEH (status) or 
OFDH (input) or 
char (output) 


Returned Value: 






Register A: 


char or status (no value) 



CP/M 3 supports direct I/O to the logical console, CONIN:, for those specialized 
applications where unadorned console input and output is required. Use Direct Con- 
sole I/O carefully because it bypasses all the normal control character functions. 
Programs that perform direct I/O through the BIOS under previous releases of CP/M 
should be changed to use direct I/O so that they can be fully supported under future 
releases of MP/M and CP/M. 

A program calls Function 6 by passing one of four different values in register E. 
The values and their meanings are summarized in Table 3-1. 
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Table 3-1. Function 6 Entry Parameters 



Register 
E value 



Meaning 



OFFH 



OFEH 



OFDH 



ASCII 
character 



Console input/status command returns an input character; if no 
character is ready, a value of zero is returned. 

Console status command (On return, register A contains 00 if no 
character is ready; otherwise it contains FFH.) 

Console input command, returns an input character; this func- 
tion will suspend the calling process until a character is ready. 

Function 6 assumes that register E contains a valid ASCII char- 
acter and sends it to the console. 
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BDOS FUNCTION 7: AUXILIARY INPUT STATUS 



Entry Parameters: 

Register C: 07H 

Returned Value: 

Register A: Auxiliary Input Status 



The Auxiliary Input Status function returns the value OFFH in register A if a 
character is ready for input from the logical auxiliary input device, AUXIN:. If no 
character is ready for input, the value 00H is returned. 
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BDOS FUNCTION 8: AUXILIARY OUTPUT STATUS 



Entry Parameters: 

Register C: 08H 

Returned Value: 

Register A: Auxiliary Output Status 



The Auxiliary Output Status function returns the value OFFH in register A if the 
logical auxiliary output device, AUXOUT:, is ready to accept a character for output. 
If the device is not ready for output, the value 00H is returned. 
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3 BDOS Calls: Function 9 



BDOS FUNCTION 9: PRINT STRING 



Entry Parameters: 
Registers C: 
DE: 



09H 

String Address 



The Print String function sends the character string addressed by register pair DE 
to the logical console, CONOUT:, until it encounters a delimiter in the string. Usu- 
ally the delimiter is a dollar sign, $, but it can be changed to any other value by 
Function 110, Get/Set Output Delimiter. If the Console Mode is in the default state 
(see Section 2.2.1), Function 9 expands tab characters, CTRL-I, in columns of 8 
characters. It also checks for stop scroll, CTRL-S, start scroll, CTRL-Q, and echoes 
to the logical list device, LST:, if printer echo, CTRL-P, has been invoked. 
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BDOS FUNCTION 10: READ CONSOLE BUFFER 



Entry Parameters: 

Registers C: OAH 

DE: Buffer Address 

Returned Value: 

Console Characters in Buffer 



The Read Console Buffer function reads a line of edited console input from the 
logical console, CONIN:, to a buffer that register pair DE addresses. It terminates 
input and returns to the calling program when it encounters a return, CTRL-M, or a 
line feed, CTRL-J, character. Function 10 also discards all input characters after the 
input buffer is filled. In addition, it outputs a bell character, CTRL-G, to the console 
when it discards a character to signal the user that the buffer is full. The input buffer 
addressed by DE has the following format: 



DE: +0 +1 +2 +3 +4 + 5 + 6 +7 +; 



+ n 



mx 


nc 


cl 


c2 


c3 


c4 


c5 


c6 


c7 




?? 



where mx is the maximum number of characters which the buffer holds, and nc is 
the number of characters placed in the buffer. The characters entered by the operator 
follow the nc value. The value mx must be set prior to making a Function 10 call 
and may range in value from 1 to 255. Setting mx to zero is equivalent to setting mx 
to one. The value nc is returned to the calling program and may range from zero to 
mx. If nc < mx, then uninitialized positions follow the last character, denoted by ?? 
in the figure. Note that a terminating return or line feed character is not placed in 
the buffer and not included in the count nc. 

If register pair DE is set to zero, Function 10 assumes that an initialized input 
buffer is located at the current DMA address (see Function 26, Set DMA Address). 
This allows a program to put a string on the screen for the user to edit. To initialize 
the input buffer, set characters cl through en to the initial value followed by a binary 
zero terminator. 
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When a program calls Function 10 with an initialized buffer, Function 10 operates 
as if the user had typed in the string. When Function 10 encounters the binary zero 
terminator, it accepts input from the console. At this point, the user can edit the 
initialized string or accept it as it is by pressing the RETURN key. However, if the 
initialized string contains a return, CTRL-M, or a linefeed, CTRL-J, character, Func- 
tion 10 returns to the calling program without giving the user the opportunity to edit 
the string. 

The level of console editing supported by Function 10 differs for the banked and 
nonbanked versions of CP/M 3. Refer to the CP/M Plus (CP/M Version 3) Operating 
System User's Guide for a detailed description of console editing. In the nonbanked 
version, Function 10 recognizes the edit control characters summarized in Table 3-2. 



Table 3-2. Edit Control Characters (Nonbanked CP/M 3) 



Character 


Edit Control Function 


rub/del 


Removes and echoes the last character; GENCPM can change 
this function to CTRL-H 


CTRL-C 


Reboots when at the beginning of line; the Console Mode can 
disable this function 


CTRL-E 


Causes physical end of line 


CTRL-H 


Backspaces one character position; GENCPM can change this 
function to rub/del 


CTRL-J 


(Line-feed) terminates input line 


CTRL-M 


(Return) terminates input line 


CTRL-P 


Echoes console output to the list device 


CTRL-R 


Retypes the current line after new line 


CTRL-U 


Removes current line after new line 


CTRL-X 


Backspaces to beginning of current line 
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The banked version of CP/M 3 expands upon the editing provided in the non- 
banked version. The functionality of the two versions is similar when the cursor is 
positioned at the end of the line. However, in the banked version, the user can move 
the cursor anywhere in the current line, insert characters, delete characters, and 
perform other editing functions. In addition, the banked version saves the previous 
command line; it can be recalled when the current line is empty. Table 3-3 summa- 
rizes the edit control characters supported by Function 10 in the banked version of 
CP/M 3. 



Table 3-3. Edit Control Characters (Banked CP/M 3) 



Character 


Edit Control Function 


rub/del 


Removes and echoes the last character if at the end of the line; 
otherwise deletes the character to the left of the current cursor 
position; GENCPM can change this function to CTRL-H. 


CTRL-A 


Moves cursor one character to the left. 


CTRL-B 


Moves cursor to the beginning of the line when not at the begin- 
ning; otherwise moves cursor to the end of the line. 


CTRL-C 


Reboots when at the beginning of line; the Console Mode can 
disable this function. 


CTRL-E 


Causes physical end-of-line; if the cursor is positioned in the 
middle of a line, the characters at and to the right of the cursor 
are displayed on the next line. 


CTRL-F 


Moves cursor one character to the right. 


CTRL-G 


Deletes the character at the current cursor position when in the 
middle of the line; has no effect when the cursor is at the end of 
the line. 


CTRL-H 


Backspaces one character position when positioned at the end 
of the line; otherwise deletes the character to the left of the 
cursor; GENCPM can change this function to rub/del. 



3-14 



I DIGITAL RESEARCH 7 



CP/M 3 Programmer's Guide 



3 BDOS Calls: Function 10 



Table 3-3. (continued) 



Character 


Edit Control Function 


CTRL-J 


(Line-feed) terminates input; the cursor can be positioned any- 
where in the line; the entire input line is accepted; sets the pre- 
vious line buffer to the input line. 


CTRL-K 


Deletes all characters to the right of the cursor along with the 
character at the cursor. 


CTRL-M 


(Return) terminates input; the cursor can be positioned any- 
where in the line; the entire input line is accepted; sets the pre- 
vious line buffer to the input line. 


CTRL-P 


Echoes console output to the list device. 


CTRL-R 


Retypes the characters to the left of the cursor on the new line. 


CTRL-U 


Updates the previous line buffer to contain the characters to the 
left of the cursor; deletes current line, and advances to new line. 


CTRL-W 


Recalls previous line if current line is empty; otherwise moves 
cursor to end-of-line. 


CTRL-X 


Deletes all characters to the left of the cursor. 



For banked systems, Function 10 uses the console width field defined in the System 
Control Block. If the console width is exceeded when the cursor is positioned at the 
end of the line, Function 10 automatically advances to the next line. The beginning 
of the line can be edited by entering a CTRL-R. 

When a character is typed while the cursor is positioned in the middle of the line, 
the typed character is inserted into the line. Characters at and to the right of the 
cursor are shifted to the right. If the console width is exceeded, the characters disap- 
pear off the right of the screen. However, these characters are not lost. They reappear 
if characters are deleted out of the line, or if a CTRL-E is typed. 
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BDOS FUNCTION 11: GET CONSOLE STATUS 



Entry Parameters: 

Register C: OBH 

Returned Value: 

Register A: Console Status 



The Get Console Status function checks to see if a character has been typed at 
the logical console, CONIN:. If the Console Mode is in the default state (see 
Section 2.2.1), Function 11 returns the value 01H in register A when a character is 
ready. If a character is not ready, it returns a value of 00H. 

If the Console Mode is in CTRL-C Only Status mode, Function 11 returns the 
value 01H in register A only if a CTRL-C has been typed at the console. 
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BDOS FUNCTION 12: RETURN VERSION NUMBER 



Entry Parameters: 

Register C: OCH 

Returned Value: 

Register HL: Version Number 



The Return Version Number function provides information that allows version 
independent programming. It returns a two-byte value in register pair HL: H con- 
tains 00H for CP/M and L contains 31H, the BDOS file system version number. 
Function 12 is useful for writing applications programs that must run on multiple 
versions of CP/M and MP/M. 
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BDOS FUNCTION 13: RESET DISK SYSTEM 



Entry Parameters: 

Register C: ODH 



The Reset Disk System function restores the file system to a reset state where all 
the disk drives are set to read-write (see Functions 28 and 29), the default disk is set 
to drive A, and the default DMA address is reset to 00 8 OH. This function can be 
used, for example, by an application program that requires disk changes during 
operation. Function 37, Reset Drive, can also be used for this purpose. 
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BDOS FUNCTION 14: SELECT DISK 



Entry Parameters: 

Registers C: OEH 

E: Selected Disk 

Returned Value: 

Registers A: Error Flag 

H: Physical Error 



The Select Disk function designates the disk drive named in register E as the 
default disk for subsequent BDOS file operations. Register E is set to for drive A, 
1 for drive B, and so on through 15 for drive P in a full 16-drive system. In addition, 
Function 14 logs in the designated drive if it is currently in the reset state. Logging- 
in a drive activates the drive's directory until the next disk system reset or drive reset 
operation. 

FCBs that specify drive code zero (dr = 00H) automatically reference the currently 
selected default drive. FCBs with drive code values between 1 and 16, however, 
ignore the selected default drive and directly reference drives A through P. 

Upon return, register A contains a zero if the select operation was successful. If a 
physical error was encountered, the select function performs different actions depend- 
ing on the BDOS error mode (see Function 45). If the BDOS error mode is in the 
default mode, a message identifying the error is displayed at the console, and the 
calling program is terminated. Otherwise, the select function returns to the calling 
program with register A set to OFFH and register H set to one of the following 
physical error codes: 



01 
04 



Disk I/O Error 
Invalid drive 
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BDOS FUNCTION 15: OPEN FILE 



Entry Parameters: 

Registers C: OFH 

DE: FCB Address 

Returned Value: 

Registers A: Directory Code 

H: Physical or Extended Error 



The Open File function activates the FCB for a file that exists in the disk directory 
under the currently active user number or user zero. The calling program passes the 
address of the FCB in register pair DE, with byte of the FCB specifying the drive, 
bytes 1 through 11 specifying the filename and filetype, and byte 12 specifying the 
extent. Usually, byte 12 of the FCB is initialized to zero. 

If the file is password protected in Read mode, the correct password must be 
placed in the first eight bytes of the current DMA, or have been previously estab- 
lished as the default password (see Function 106). If the current record field of the 
FCB, cr, is set to OFFH, Function 15 returns the byte count of the last record of the 
file in the cr field. You can set the last record byte count for a file with Function 30, 
Set File Attributes. Note that the current record field of the FCB, cr, must be zeroed 
by the calling program before beginning read or write operations if the file is to be 
accessed sequentially from the first record. 

If the current user is non-zero, and the file to be opened does not exist under the 
current user number, the open function searches user zero for the file. If the file exists 
under user zero, and has the system attribute, t2', set, the file is opened under user 
zero. Write operations are not supported for a file that is opened under user zero in 
this manner. 
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If the open operation is successful, the user's FCB is activated for read and write 
operations. The relevant directory information is copied from the matching directory 
FCB into bytes dO through dn of the FCB. If the file is opened under user zero when 
the current user number is not zero, interface attribute f8' is set to one in the user's 
FCB. In addition, if the referenced file is password protected in Write mode, and the 
correct password was not passed in the DMA, or did not match the default pass- 
word, interface attribute f7' is set to one. Write operations are not supported for an 
activated FCB if interface attribute f7' or f8' is true. 

When the open operation is successful, the open function also makes an Access 
date and time stamp for the opened file when the following conditions are satisfied: 
the referenced drive has a directory label that requests Access date and time stamp- 
ing, and the FCB extent number field is zero. 

Upon return, the Open File function returns a directory code in register A with the 
value 00H if the open was successful, or FFH, 255 decimal, if the file was not found. 
Register H is set to zero in both of these cases. If a physical or extended error was 
encountered, the Open File function performs different actions depending on the 
BDOS error mode (see Function 45). If the BDOS error mode is in the default mode, 
a message identifying the error is displayed at the console and the program is termi- 
nated. Otherwise, the Open File function returns to the calling program with register 
A set to OFFH, and register H set to one of the following physical or extended error 
codes: 

01 : Disk I/O Error 

04 : Invalid drive error 

07 : File password error 

09 : ? in the FCB filename or filetype field 
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BDOS FUNCTION 16: CLOSE FILE 



Entry Parameters: 

Registers C: 10H 

DE: FCB Address 

Returned Value: 

Registers A: Directory Code 

H: Physical or Extended Error 



The Close File function performs the inverse of the Open File function. The calling 
program passes the address of an FCB in register pair DE. The referenced FCB must 
have been previously activated by a successful Open or Make function call (see 
Functions 15 and 22). Interface attribute f5' specifies how the file is to be closed as 
shown below: 

f5' = - Permanent close (default mode) 
£5* = 1 - Partial close 

A permanent close operation indicates that the program has completed file operations 
on the file. A partial close operation updates the directory, but indicates that the file 
is to be maintained in the open state. 

If the referenced FCB contains new information because of write operations to the 
FCB, the close function permanently records the new information in the referenced 
disk directory. Note that the FCB does not contain new information, and the direc- 
tory update step is bypassed if only read or update operations have been made to the 
referenced FCB. 



I DIGITAL RESEARCH 7 



3-22 



CP/M 3 Programmer's Guide 3 BDOS Calls: Function 16 

Upon return, the close function returns a directory code in register A with the 
value 00H if the close was successful, or FFH, 255 Decimal, if the file was not found. 
Register H is set to zero in both of these cases. If a physical or extended error is 
encountered, the close function performs different actions depending on the BDOS 
error mode (see Function 45). If the BDOS error mode is in the default mode, a 
message identifying the error is displayed at the console, and the calling program is 
terminated. Otherwise, the close function returns to the calling program with register 
A set to OFFH and register H set to one of the following physical error codes: 

01 : Disk I/O error 

02 : Read/only disk 
04 : Invalid drive error 
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BDOS FUNCTION 17: SEARCH FOR FIRST 



Entry Parameters: 

Registers C: 11H 

DE: FCB Address 

Returned Value: 

Registers A: Directory Code 

H: Physical Error 



The Search For First function scans the directory for a match with the FCB addressed 
by register pair DE. Two types of searches can be performed. For standard searches, 
the calling program initializes bytes through 12 of the referenced FCB, with byte 
specifying the drive directory to be searched, bytes 1 through 1 1 specifying the file or 
files to be searched for, and byte 12 specifying the extent. Usually byte 12 is set to 
zero. An ASCII question mark, 63 decimal, 3F hex, in any of the bytes 1 through 12 
matches all entries on the directory in the corresponding position. This facility, called 
ambiguous reference, can be used to search for multiple files on the directory. When 
called in the standard mode, the Search function scans for the first file entry in the 
specified directory that matches the FCB, and belongs to the current user number. 

The Search For First function also initializes the Search For Next function. After 
the Search function has located the first directory entry matching the referenced FCB, 
the Search For Next function can be called repeatedly to locate all remaining match- 
ing entries. In terms of execution sequence, however, the Search For Next call must 
either follow a Search For First or Search For Next call with no other intervening 
BDOS disk-related function calls. 

If byte of the referenced FCB is set to a question mark, the Search function 
ignores the remainder of the referenced FCB, and locates the first directory entry 
residing on the current default drive. All remaining directory entries can be located 
by making multiple Search For Next calls. This type of search operation is not 
usually made by application programs, but it does provide complete flexibility to 
scan all current directory values. Note that this type of search operation must be 
performed to access a drive's directory label (see Section 2.3.6). 
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Upon return, the Search function returns a Directory Code in register A with the 
value to 3 if the search is successful, or OFFH, 255 Decimal, if a matching directory 
entry is not found. Register H is set to zero in both of these cases. For successful 
searches, the current DMA is also filled with the directory record containing the 
matching entry, and the relative starting position is A * 32 (that is, rotate the A 
register left 5 bits, or ADD A five times). Although it is not usually required for 
application programs, the directory information can be extracted from the buffer at 
this position. 

If the directory has been initialized for date and time stamping by INITDIR, then 
an SFCB resides in every fourth directory entry, and successful Directory Codes are 
restricted to the values to 2. For successful searches, if the matching directory 
record is an extent zero entry, and if an SFCB resides at offset 96 within the current 
DMA, contents of (DMA Address + 96) = 21H, the SFCB contains the date and 
time stamp information, and password mode for the file. This information is located 
at the relative starting position of 97 + (A * 10) within the current DMA in the 
following format: 

- 3 : Create or Access Date and Time Stamp Field 
4 - 7 : Update Date and Time Stamp Field 

8 : Password Mode Field 

(Refer to Section 2.3.8 for more information on SFCBs.) 

If a physical error is encountered, the Search function performs different actions 
depending on the BDOS error mode (see Function 45). If the BDOS error mode is in 
the default mode, a message identifying the error is displayed at the console, and the 
calling program is terminated. Otherwise, the Search function returns to the calling 
program with register A set to OFFH, and register H set to one of the following 
physical error codes: 

01 : Disk I/O error 

04 : Invalid drive error 
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BDOS FUNCTION 18: SEARCH FOR NEXT 



Entry Parameters: 

Register C: 12H 

Returned Value: 

Registers A: Directory Code 
H: Physical Error 



The Search For Next function is identical to the Search For First function, except 
that the directory scan continues from the last entry that was matched. Function 18 
returns a Directory code in register A, analogous to Function 17. 

Note: in execution sequence, a Function 18 call must follow either a Function 17 or 
another Function 18 call with no other intervening BDOS disk-related function calls. 
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BDOS FUNCTION 19: DELETE FILE 


Entry Parameters: 




Registers C: 


13H 


DE: 


FCB Address 


Returned Value: 




Registers A: 


Directory Code 


H: 


Extended or Physical Error 



The Delete File function removes files or XFCBs that match the FCB addressed in 
register pair DE. The filename and filetype can contain ambiguous references, that is, 
question marks in bytes fl through t3, but the dr byte cannot be ambiguous, as it 
can in the Search and Search Next functions. Interface attribute f5' specifies the type 
of delete operation that is performed. 

f5' = - Standard Delete (default mode) 
f5' = 1 - Delete only XFCBs 

If any of the files that the referenced FCB specify are password protected, the correct 
password must be placed in the first eight bytes of the current DMA buffer, or have 
been previously established as the default password (see Function 106). 

For standard delete operations, the Delete function removes all directory entries 
belonging to files that match the referenced FCB. All disk directory and data space 
owned by the deleted files is returned to free space, and becomes available for allo- 
cation to other files. Directory XFCBs that were owned by the deleted files are also 
removed from the directory. If interface attribute f5' of the FCB is set to 1, Function 
19 deletes only the directory XFCBs that match the referenced FCB. 

Note: if any of the files that match the input FCB specification fail the password 
check, or are Read-Only, then the Delete function does not delete any files or XFCBs. 
This applies to both types of delete operations. 
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In nonbanked systems, file passwords and XFCBs are not supported. Thus, if the 
Delete function is called with interface attribute f5' set to true, the Delete function 
performs no action but returns with register A set to zero. 

Upon return, the Delete function returns a Directory Code in register A with the 
value if the delete is successful, or OFFH, 255 Decimal, if no file that matches the 
referenced FCB is found. Register H is set to zero in both of these cases. If a physical, 
or extended error is encountered, the Delete function performs different actions 
depending on the BDOS error mode (see Function 45). If the BDOS error mode is 
the default mode, a message identifying the error is displayed at the console and the 
calling program is terminated. Otherwise, the Delete function returns to the calling 
program with register A set to OFFH and register H set to one of the following 
physical or extended error codes: 

01 : Disk I/O error 

02 : Read-Only disk 

03 : Read-Only file 

04 : Invalid drive error 
07 : File password error 
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BDOS FUNCTION 20: READ SEQUENTIAL 


Entry Parameters: 
Registers C: 
DE: 

Returned Value: 
Registers A: 
H: 


14H 

FCB Address 

Error Code 
Physical Error 



The Read Sequential function reads the next 1 to 128 128-byte records from a file 
into memory beginning at the current DMA address. The BDOS Multi-Sector Count 
(see Function 44) determines the number of records to be read. The default is one 
record. The FCB addressed by register pair DE must have been previously activated 
by an Open or Make function call. 

Function 20 reads each record from byte cr of the extent, then automatically 
increments the cr field to the next record position. If the cr field overflows, then the 
function automatically opens the next logical extent and resets the cr field to in 
preparation for the next read operation. The calling program must set the cr field to 
following the Open call if the intent is to read sequentially from the beginning of 
the file. 

Upon return, the Read Sequential function sets register A to zero if the read oper- 
ation is successful. Otherwise, register A contains an error code identifying the error 
as shown below: 

01 : Reading unwritten data (end-of-file) 

09 : Invalid FCB 

10 : Media change occurred 

255 : Physical Error; refer to register H 
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Error Code 01 is returned if no data exists at the next record position of the file. 
Usually, the no data situation is encountered at the end of a file. However, it can 
also occur if an attempt is made to read a data block that has not been previously 
written, or an extent which has not been created. These situations are usually restricted 
to files created or appended with the BDOS random write functions (see Functions 
34 and 40). 

Error Code 09 is returned if the FCB is invalidated by a previous BDOS close call that 
returns an error. 

Error Code 10 is returned if a media change occurs on the drive after the refer- 
enced FCB is activated by a BDOS Open, or Make Call. 

Error Code 255 is returned if a physical error is encountered and the BDOS error 
mode is Return Error mode, or Return and Display Error mode (see Function 45). If 
the error mode is the default mode, a message identifying the physical error is dis- 
played at the console, and the calling program is terminated. When a physical error 
is returned to the calling program, register H contains one of the following error 
codes: 

01 : Disk I/O error 
04 : Invalid drive error 

On all error returns except for physical error returns, A = 255, Function 20 sets 
register H to the number of records successfully read before the error is encountered. 
This value can range from to 127 depending on the current BDOS Multi-Sector 
Count. It is always set to zero when the Multi-Sector Count is equal to one. 
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BDOS FUNCTION 21: WRITE SEQUENTIAL 



Entry Parameters: 

Registers C: 15H 

DE: FCB Address 

Returned Value: 

Registers A: Error Code 

H: Physical Error 



The Write Sequential function writes 1 to 128 128-byte data records, beginning at 
the current DMA address into the file named by the FCB addressed in register pair 
DE. The BDOS Multi-Sector Count (see Function 44) determines the number of 128 
byte records that are written. The default is one record. The referenced FCB must 
have been previously activated by a BDOS Open or Make function call. 

Function 21 places the record into the file at the position indicated by the cr byte 
of the FCB, and then automatically increments the cr byte to the next record posi- 
tion. If the cr field overflows, the function automatically opens, or creates the next 
logical extent, and resets the cr field to in preparation for the next write operation. 
If Function 21 is used to write to an existing file, then the newly written records 
overlay those already existing in the file. The calling program must set the cr field to 
following an Open or Make call if the intent is to write sequentially from the 
beginning of the file. 

Function 21 makes an Update date and time for the file if the following conditions 
are satisfied: the referenced drive has a directory label that requests date and time 
stamping, and the file has not already been stamped for update by a previous Make 
or Write function call. 
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Upon return, the Write Sequential function sets register A to zero if the write 
operation is successful. Otherwise, register A contains an error code identifying the 
error as shown below: 

01 : No available directory space 

02 : No available data block 

09 : Invalid FCB 

10 : Media change occurred 

255 : Physical Error : refer to register H 

Error Code 01 is returned when the write function attempts to create a new extent 
that requires a new directory entry, and no available directory entries exist on the 
selected disk drive. 

Error Code 02 is returned when the write command attempts to allocate a new 
data block to the file, and no unallocated data blocks exist on the selected disk drive. 

Error Code 09 is returned if the FCB is invalidated by a previous BDOS close call 
that returns an error. 

Error Code 10 is returned if a media change occurs on the drive after the refer- 
enced FCB is activated by a BDOS Open or Make call. 
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Error Code 255 is returned if a physical error is encountered and the BDOS error 
mode is Return Error mode, or Return and Display Error mode (see Function 45). If 
the error mode is the default mode, a message identifying the physical error is dis- 
played at the console, and the calling program is terminated. When a physical error 
is returned to the calling program, register H contains one of the following error 
codes: 

01 : Disk I/O error 

02 : Read-Only disk 

03 : Read-Only file or 

File open from user when 

the current user number is non-zero or 

File password protected in Write mode 

04 : Invalid drive error 

On all error returns, except for physical error returns, A = 255, Function 21 sets 
register H to the number of records successfully written before the error was encoun- 
tered. This value can range from to 127 depending on the current BDOS Multi- 
Sector Count. It is always set to zero when the Multi-Sector Count is set to one. 
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BDOS FUNCTION 22: MAKE FILE 


*> Entry Parameters: 
Registers C: 
DE: 

Returned Value: 
Registers A: 
H: 


16H 

FCB Address 

Directory Code 

Physical or Extended Error 



The Make File function creates a new directory entry for a file under the current 
user number. It also creates an XFCB for the file if the referenced drive has a direc- 
tory label that enables password protection on the drive, and the calling program 
assigns a password to the file. 

The calling program passes the address of the FCB in register pair DE, with byte 
of the FCB specifying the drive, bytes 1 through 11 specifying the filename and 
filetype, and byte 12 set to the extent number. Usually, byte 12 is set to zero. Byte 
32 of the FCB, the cr field, must be initialized to zero, before or after the Make call, 
if the intent is to write sequentially from the beginning of the file. 

Interface attribute f6' specifies whether a password is to be assigned to the created 
file. 

f6' = - Do not assign password (default) 
f6' = 1 - Assign password to created file 

When attribute f6' is set to 1, the calling program must place the password in the 
first 8 bytes of the current DMA buffer, and set byte 9 of the DMA buffer to the 
password mode (see Function 102). Note that the Make function only interrogates 
interface attribute f6' if passwords are activated on the referenced drive. In non- 
banked systems, file passwords are not supported, and attribute f6' is never interrogated. 

The Make function returns with an error if the referenced FCB names a file that 
currently exists in the directory under the current user number. 
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If the Make function is successful, it activates the referenced FCB for file opera- 
tions by opening the FCB, and initializes both the directory entry and the referenced 
FCB to an empty file. It also initializes all file attributes to zero. In addition, Function 
22 makes a Creation date and time stamp for the file if the following conditions are 
satisfied: the referenced drive has a directory label that requests Creation date and 
time stamping and the FCB extent number field is equal to zero. Function 22 also 
makes an Update stamp if the directory label requests update stamping and the FCB 
extent field is equal to zero. 

If the referenced drive contains a directory label that enables password protection, 
and if interface attribute f6' has been set to 1, the Make function creates an XFCB 
for the file. In addition, Function 22 also assigns the password, and password mode 
placed in the first nine bytes of the DMA, to the XFCB. 

Upon return, the Make function returns a directory code in register A with the 
value if the make operation is successful, or OFFH, 255 decimal, if no directory 
space is available. Register H is set to zero in both of these cases. If a physical or 
extended error is encountered, the Make function performs different actions depend- 
ing on the BDOS error mode (see Function 45). If the BDOS error mode is the 
default mode, a message identifying the error is displayed at the console, and the 
calling program is terminated. Otherwise, the Make function returns to the calling 
program with register A set to OFFH, and register H set to one of the following 
physical or extended error codes: 

01 : Disk I/O error 

02 : Read-Only disk 
04 : Invalid drive error 

08 : File already exists 

09 : ? in filename or filetype field 
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BDOS FUNCTION 23 : RENAME FILE 



Entry Parameters: 

Registers C: 17H 

DE: FCB Address 

Returned Value: 

Registers A: Directory Code 

H: Physical or Extended Error 



The Rename function uses the FCB, addressed by register pair DE, to change all 
directory entries of the file specified by the filename in the first 16 bytes of the FCB 
to the filename in the second 16 bytes. If the file specified by the first filename is 
password protected, the correct password must be placed in the first eight bytes of 
the current DMA buffer, or have been previously established as the default password 
(see Function 106). The calling program must also ensure that the filenames specified 
in the FCB are valid and unambiguous, and that the new filename does not already 
exist on the drive. Function 23 uses the dr code at byte of the FCB to select the 
drive. The drive code at byte 16 of the FCB is ignored. 
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Upon return, the Rename function returns a Directory Code in register A with the 
value if the rename is successful, or OFFH, 255 Decimal, if the file named by the 
first filename in the FCB is not found. Register H is set to zero in both of these cases. 
If a physical or extended error is encountered, the Rename function performs differ- 
ent actions depending on the BDOS error mode (see Function 45). If the BDOS error 
mode is the default mode, a message identifying the error is displayed at the console 
and the program is terminated. Otherwise, the Rename function returns to the calling 
program with register A set to OFFH and register H set to one of the following 
physical or extended error codes: 

01 : Disk I/O error 

02 : Read-Only disk 

03 : Read-Only file 

04 : Invalid drive error 

07 : File password error 

08 : File already exists 

09 : ? in filename or filetype field 
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BDOS FUNCTION 24: RETURN LOGIN VECTOR 



Entry Parameters: 

Register C: 18H 

Returned Value: 

Register HL: Login Vector 



Function 24 returns the login vector in register pair HL. The login vector is a 16- 
bit value with the least significant bit of L corresponding to drive A, and the high- 
order bit of H corresponding to the 16th drive, labelled P. A bit indicates that the 
drive is not on-line, while a 1 bit indicates the drive is active. A drive is made active 
by either an explicit BDOS Select Disk call, number 14, or an implicit selection when 
a BDOS file operation specifies a non-zero dr byte in the FCB. Function 24 maintains 
compatibilty with earlier releases since registers A and L contain the same values 
upon return. 
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BDOS FUNCTION 25: RETURN CURRENT DISK 



Entry Parameters: 

Register C: 19H 

Returned Value: 

Register A: Current Disk 



Function 25 returns the currently selected default disk number in register A. The 
disk numbers range from through 15 corresponding to drives A through P. 
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BDOS FUNCTION 26: SET DMA ADDRESS 



Entry Parameters: 
Registers C: 
DE: 



1AH 

DMA Address 



DMA is an acronym for Direct Memory Address, which is often used in connec- 
tion with disk controllers that directly access the memory of the computer to transfer 
data to and from the disk subsystem. Under CP/M 3, the current DMA is usually 
defined as the buffer in memory where a record resides before a disk write, and after 
a disk read operation. If the BDOS Multi-Sector Count is equal to one (see Function 
44), the size of the buffer is 128 bytes. However, if the BDOS Multi-Sector Count is 
greater than one, the size of the buffer must equal N * 128, where N equals the 
Multi-Sector Count. 

Some BDOS functions also use the current DMA to pass parameters, and to return 
values. For example, BDOS functions that check and assign file passwords require 
that the password be placed in the current DMA. As another example, Function 46, 
Get Disk Free Space, returns its results in the first 3 bytes of the current DMA. When 
the current DMA is used in this context, the size of the buffer in memory is deter- 
mined by the specific requirements of the called function. 

When a transient program is initiated by the CCP, its DMA address is set to 
0080H. The BDOS Reset Disk System function, Function 13, also sets the DMA 
address to 0080H. The Set DMA function can change this default value to another 
memory address. The DMA address is set to the value passed in the register pair DE. 
The DMA address remains at this value until it is changed by another Set DMA 
Address, or Reset Disk System call. 
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BDOS FUNCTION 27: GET ADDR(ALLOC) 



Entry Parameters: 

Register C: 1BH 

Returned Value: 

Register HL: ALLOC Address 



CP/M 3 maintains an allocation vector in main memory for each active disk drive. 
Some programs use the information provided by the allocation vector to determine 
the amount of free data space on a drive. Note, however, that the allocation infor- 
mation might be inaccurate if the drive has been marked Read-Only. 

Function 27 returns in register pair HL, the base address of the allocation vector 
for the currently selected drive. If a physical error is encountered when the BDOS 
error mode is one of the return modes (see Function 45), Function 27 returns the 
value OFFFFH in the register pair HL. 

In banked CP/M 3 systems, the allocation vector can be placed in bank zero. In 
this case, a transient program cannot access the allocation vector. However, the 
BDOS function, Get Disk Free Space (Function 46), can be used to directly return 
the number of free 128-byte records on a drive. The CP/M 3 utilities that display a 
drive's free space, DIR and SHOW, use Function 46 for that purpose. 



DIGITAL RESEARCH 1 



3-41 



3 BDOS Calls: Function 28 



CP/M 3 Programmer's Guide 



BDOS FUNCTION 28: WRITE PROTECT DISK 



Entry Parameters: 

Register C: 1CH 



The Write Protect Disk function provides temporary write protection for the cur- 
rently selected disk by marking the drive as Read-Only. No program can write to a 
disk that is in the Read-Only state. A drive reset operation must be performed for a 
Read-Only drive to restore it to the Read- Write state (see Functions 13 and 37). 
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BDOS FUNCTION 29: GET READ-ONLY VECTOR 



Entry Parameters: 

Register C: 1DH 

Returned Value: 

Register HL: R/O Vector Value 



Function 29 returns a bit vector in register pair HL that indicates which drives 
have the temporary Read-Only bit set. The Read-Only bit can be set only by a BDOS 
Write Protect Disk call. 

The format of the bit vector is analagous to that of the login vector returned by 
Function 24. The least significant bit corresponds to drive A, while the most signifi- 
cant bit corresponds to drive P. 
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BDOS FUNCTION 30: SET FILE ATTRIBUTES 



Entry Parameters: 

Registers C: 1EH 

DE: FCB Address 

Returned Value: 

Registers A: Directory Code 

H: Physical or Extended error 



By calling the Set File Attributes function, a program can modify a file's attributes 
and set its last record byte count. Other BDOS functions can be called to interrogate 
these file parameters, but only Function 30 can change them. The file attributes that 
can be set or reset by Function 30 are fl' through f4', Read-Only, tl', System, t2', 
and Archive, t3'. The register pair DE addresses an FCB containing a filename with 
the appropriate attributes set or reset. The calling program must ensure that it does 
not specify an ambiguous filename. In addition, if the specified file is password pro- 
tected, the correct password must be placed in the first eight bytes of the current 
DMA buffer or have been previously established as the default password (see Func- 
tion 106). 

Interface attribute f6' specifies whether the last record byte count of the specified 
file is to be set: 

f6' = - Do not set byte count (default mode) 
f6' = 1 - Set byte count 

If interface attribute f6' is set, the calling program must set the cr field of the refer- 
enced FCB to the byte count value. A program can access a file's byte count value 
with the BDOS Open, Search, or Search Next functions. 

Function 30 searches the referenced directory for entries belonging to the current 
user number that matches the FCB specified name and type fields. The function then 
updates the directory to contain the selected indicators, and if interface attribute f6' 
is set, the specified byte count value. Note that the last record byte count is main- 
tained in byte 13 of a file's directory FCBs. 
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File attributes tl', t2', and t3' are defined by CP/M 3. (They are described in 
Section 2.3.4.) Attributes fl' through f4' are not presently used, but can be useful for 
application programs, because they are not involved in the matching program used 
by the BDOS during Open File and Close File operations. Indicators f5' through f8' 
are reserved for use as interface attributes. 

Upon return, Function 30 returns a Directory Code in register A with the value 
if the function is successful, or OFFH, 255 Decimal, if the file specified by the refer- 
enced FCB is not found. Register H is set to zero in both of these cases. If a physical 
or extended error is encountered, the Set File Attributes function performs different 
actions depending on the BDOS error mode (see Function 45). If the BDOS error 
mode is the default mode, a message identifying the error is displayed at the console, 
and the program is terminated. Otherwise, Function 30 returns to the calling pro- 
gram with register A set to OFFH, and register H set to one of the following physical 
or extended error codes: 

01 : Disk I/O error 

02 : Read-Only disk 
04 : Select error 

07 : File password error 

09 : ? in filename or filetype field 
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BDOS FUNCTION 31: 


GET ADDR(DPB PARMS) 


Entry Parameters: 
Register C: 

Returned Value: 
Register HL: 


1FH 

DPB Address 



Function 31 returns in register pair HL the address of the BIOS-resident Disk 
Parameter Block, DPB, for the currently selected drive. (Refer to the CP/M Plus 
(CP/M Version 3) Operating System System Guide for the format of the DPB). The 
calling program can use this address to extract the disk parameter values. 

If a physical error is encountered when the BDOS error mode is one of the return 
modes (see Function 45), Function 31 returns the value OFFFFH in the register pair 
HL. 
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BDOS FUNCTION 32: SET/GET USER CODE 


Entry Parameters: 
Registers C: 
E: 

Returned Value: 

Register A: 


20H 

OFFH (get) or 

Current Code 
(no value) 


User Code (set) 
or 



A program can change, or interrogate the currently active user number by calling 
Function 32. If register E = OFFH, then the value of the current user number is 
returned in register A, where the value is in the range of to 15. If register E is not 
OFFH, then the current user number is changed to the value of E, modulo 16. 



DIGITAL RESEARCH 1 



3-47 



3 BDOS Calls: Function 33 



CP/M 3 Programmer's Guide 



BDOS FUNCTION 33: READ RANDOM 


Entry Parameters: 
Registers C: 
DE: 

Returned Value: 
Registers A: 
H: 


21H 

FCB Address 

Error Code 
Physical Error 



The Read Random function is similar to the Read Sequential function except that 
the read operation takes place at a particular random record number, selected by the 
24-bit value constructed from the three byte, rO, rl, r2, field beginning at position 
33 of the FCB. Note that the sequence of 24 bits is stored with the least significant 
byte first, rO, the middle byte next, rl, and the high byte last, r2. The random record 
number can range from to 262,143. This corresponds to a maximum value of 3 in 
byte r2. 

To read a file with Function 33, the calling program must first open the base 
extent, extent 0. This ensures that the FCB is properly initialized for subsequent 
random access operations. The base extent may or may not contain any allocated 
data. Function 33 reads the record specified by the random record field into the 
current DMA address. The function automatically sets the logical extent and current 
record values, but unlike the Read Sequential function, it does not advance the 
current record number. Thus, a subsequent Read Random call rereads the same 
record. After a random read operation, a file can be accessed sequentially, starting 
from the current randomly accessed position. However, the last randomly accessed 
record is reread or rewritten when switching from random to sequential mode. 

If the BDOS Multi-Sector Count is greater than one (see Function 44), the Read 
Random function reads multiple consecutive records into memory beginning at the 
current DMA. The rO, rl, and r2 field of the FCB is automatically incremented to 
read each record. However, the FCBs random record number is restored to the first 
record's value upon return to the calling program. 
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Upon return, the Read Random function sets register A to zero if the read opera- 
tion was successful. Otherwise, register A contains one of the following error codes: 

01 : Reading unwritten data (end-of-file) 

03 : Cannot close current extent 

04 : Seek to unwritten extent 

06 : Random record number out of range 
10 : Media change occurred 
255 : Physical Error : refer to register H 

Error Code 01 is returned if no data exists at the next record position of the file. 
Usually, the no data situation is encountered at the end of a file. However, it can 
also occur if an attempt is made to read a data block that has not been previously 
written. 

Error Code 03 is returned when the Read Random function cannot close the 
current extent prior to moving to a new extent. 

Error Code 04 is returned when a read random operation accesses an extent that 
has not been created. 

Error Code 06 is returned when byte 35, r2, of the referenced FCB is greater than 
3. 

Error Code 10 is returned if a media change occurs on the drive after the refer- 
enced FCB is activated by a BDOS Open or Make Call. 

Error Code 255 is returned if a physical error is encountered, and the BDOS error 
mode is one of the return modes (see Function 45). If the error mode is the default 
mode, a message identifying the physical error is displayed at the console, and the 
calling program is terminated. When a physical error is returned to the calling pro- 
gram, register H contains one of the following error codes: 

01 : Disk I/O error 
04 : Invalid drive error 

On all error returns except for physical errors, A = 255, the Read Random 
function sets register H to the number of records successfully read before the error is 
encountered. This value can range from to 127 depending on the current BDOS 
Multi-Sector Count. It is always set to zero when the Multi-Sector Count is equal to 
one. 
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BDOS FUNCTION 34: WRITE RANDOM 



Entry Parameters: 

Registers C: 22H 

DE: FCB Address 

Returned Value: 

Registers A: Error Code 

H: Physical Error 



The Write Random function is analagous to the Read Random function, except 
that data is written to the disk from the current DMA address. If the disk extent or 
data block where the data is to be written is not already allocated, the BDOS auto- 
matically performs the allocation before the write operation continues. 

To write to a file using the Write Random function, the calling program must first 
open the base extent, extent 0. This ensures that the FCB is properly initialized for 
subsequent random access operations. If the file is empty, the calling program must 
create the base extent with the Make File function before calling Function 34. The 
base extent might or might not contain any allocated data, but it does record the file 
in the directory, so that the file can be displayed by the DIR utility. 

The Write Random function sets the logical extent and current record positions to 
correspond with the random record being written, but does not change the random 
record number. Thus, sequential read or write operations can follow a random write, 
with the current record being reread or rewritten as the calling program switches 
from random to sequential mode. 

Function 34 makes an Update date and time stamp for the file if the following 
conditions are satisfied: the referenced drive has a directory label that requests Update 
date and time stamping if the file has not already been stamped for update by a 
previous BDOS Make or Write call. 
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If the BDOS Multi-Sector Count is greater than one (see Function 44), the Write 
Random function reads multiple consecutive records into memory beginning at the 
current DMA. The rO, rl, and r2 field of the FCB is automatically incremented to 
write each record. However, the FCB's random record number is restored to the first 
record's value when it returns to the calling program. Upon return, the Write Ran- 
dom function sets register A to zero if the write operation is successful. Otherwise, 
register A contains one of the following error codes: 

02 : No available data block 

03 : Cannot Close current extent 

05 : No available directory space 

06 : Random record number out of range 
10 : Media change occurred 

255 : Physical Error : refer to register H 

Error Code 02 is returned when the write command attempts to allocate a new 
data block to the file and no unallocated data blocks exist on the selected disk drive. 

Error Code 03 is returned when the Write Random function cannot close the 
current extent prior to moving to a new extent. 

Error Code 05 is returned when the write function attempts to create a new extent 
that requires a new directory entry and no available directory entries exist on the 
selected disk drive. 

Error Code 06 is returned when byte 35, r2, of the referenced FCB is greater than 
3. 

Error Code 10 is returned if a media change occurs on the drive after the refer- 
enced FCB is activated by a BDOS Open or Make Call. 
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Error Code 255 is returned if a physical error is encountered and the BDOS error 
mode is one of the return modes (see Function 45). If the error mode is the default 
mode, a message identifying the physical error is displayed at the console, and the 
calling program is terminated. When a physical error is returned to the calling pro- 
gram, it is identified by register H as shown below: 

01 : Disk I/O error 

02 : Read-Only disk 

03 : Read-Only file or 

File open from user when the current user number is nonzero or 
File password protected in Write mode 

04 : Invalid drive error 

On all error returns, except for physical errors, A = 255, the Write Random 
function sets register H to the number of records successfully written before the error 
is encountered. This value can range from to 127 depending on the current BDOS 
Multi-Sector Count. It is always set to zero when the Multi-Sector Count is equal to 
one. 
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BDOS FUNCTION 35: COMPUTE FILE SIZE 



Entry Parameters: 

Registers C: 23 H 

DE: FCB Address 

Returned Value: 

Registers A: Error Flag 

H: Physical or Extended error 

Random Record Field Set 



The Compute File Size function determines the virtual file size, which is, in effect, 
the address of the record immediately following the end of the file. The virtual size 
of a file corresponds to the physical size if the file is written sequentially. If the file is 
written in random mode, gaps might exist in the allocation, and the file might con- 
tain fewer records than the indicated size. For example, if a single record with record 
number 262,143, the CP/M 3 maximum is written to a file using the Write Random 
function, then the virtual size of the file is 262,144 records even though only 1 data 
block is actually allocated. 

To compute file size, the calling program passes in register pair DE the address of 
an FCB in random mode format, bytes rO, rl and r2 present. Note that the FCB 
must contain an unambiguous filename and filetype. Function 35 sets the random 
record field of the FCB to the random record number + 1 of the last record in the 
file. If the r2 byte is set to 04, then the file contains the maximum record count 
262,144. 

A program can append data to the end of an existing file by calling Function 35 to 
set the random record position to the end of file, and then performing a sequence of 
random writes starting at the preset record address. 

Note: the BDOS does not require that the file be open to use Function 35. However, 
if the file has been written to, it must be closed before calling Function 35. Other- 
wise, an incorrect file size might be returned. 
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Upon return, Function 35 returns a zero in register A if the file specified by the 
referenced FCB is found, or an OFFH in register A if the file is not found. Register H 
is set to zero in both of these cases. If a physical error is encountered, Function 35 
performs different actions depending on the BDOS error mode (see Function 45). 
If the BDOS error mode is the default mode, a message identifying the error is 
displayed at the console and the program is terminated. Otherwise, Function 35 
returns to the calling program with register A set to OFFH, and register H set to one 
of the following physical errors: 

01 : Disk I/O error 
04 : Invalid drive error 
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BDOS FUNCTION 36: SET RANDOM RECORD 



Entry Parameters: 

Registers C: 24H 

DE: FCB Address 

Returned Value: Random Record Field Set 



The Set Random Record function returns the random record number of the next 
record to be accessed from a file that has been read or written sequentially to a 
particular point. This value is returned in the random record field, bytes rO, rl, and 
r2, of the FCB addressed by the register pair DE. Function 36 can be useful in two 
ways. 

First, it is often necessary to initially read and scan a sequential file to extract the 
positions of various key fields. As each key is encountered, Function 36 is called to 
compute the random record position for the data corresponding to this key. If the 
data unit size is 128 bytes, the resulting record number minus one is placed into a 
table with the key for later retrieval. After scanning the entire file and tabularizing 
the keys and their record numbers, you can move directly to a particular record by 
performing a random read using the corresponding random record number that you 
saved earlier. The scheme is easily generalized when variable record lengths are involved, 
because the program need only store the buffer-relative byte position along with the 
key and record number to find the exact starting position of the keyed data at a later 
time. 

A second use of Function 36 occurs when switching from a sequential read or 
write over to random read or write. A file is sequentially accessed to a particular 
point in the file, then Function 36 is called to set the record number, and subsequent 
random read and write operations continue from the next record in the file. 
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BDOS FUNCTION 37: RESET DRIVE 


Entry Parameters: 
Registers C: 
DE: 

Returned Value: 

Register A: 


25H 

Drive Vector 

00H 



The Reset Drive function programmatically restores specified drives to the reset 
state. A reset drive is not logged-in and is in Read- Write status. The passed parame- 
ter in register pair DE is a 16-bit vector of drives to be reset, where the least signifi- 
cant bit corresponds to the first drive A, and the high-order bit corresponds to the 
sixteenth drive, labelled P. Bit values of 1 indicate that the specified drive is to be 
reset. 
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BDOS FUNCTION 38: ACCESS DRIVE 



Entry Parameters: 

Register C: 26H 



This is an MP/M function that is not supported under CP/M 3. If called, the file 
system returns a zero in register A indicating that the access request is successful. 
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BDOS FUNCTION 39: FREE DRIVE 



Entry Parameters: 

Register C: 27H 



This is an MP/M function that is not supported under CP/M 3. If called, the file 
system returns a zero in register A indicating that the free request is successful. 
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BDOS FUNCTION 40: WRITE RANDOM WITH 

ZERO FILL 


Entry Parameters: 
Registers C: 
DE: 

Returned Value: 
Registers A: 
H: 


28H 

FCB address 

Error Code 
Physical Error 



The Write Random With Zero Fill function is identical to the Write Random 
function (Function 34) with the exception that a previously unallocated data block is 
filled with zeros before the record is written. If this function has been used to create 
a file, records accessed by a read random operation that contain all zeros identify 
unwritten random record numbers. Unwritten random records in allocated data blocks 
of files created using the Write Random function (Function 34) contain uninitialized 
data. 
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BDOS FUNCTION 41: TEST AND WRITE RECORD 



Entry Parameters: 

Registers C: 29H 

DE: FCB Address 

Returned Value: 

Registers A: Error Code 

H: Physical Error 



The Test and Write Record function is an MP/M II ™ function that is not sup- 
ported under CP/M 3. If called, Function 41 returns with register A set to OFFH and 
register H set to zero. 
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BDOS FUNCTION 42: LOCK RECORD 



Entry Parameters: 

Registers C: 2AH 

DE: FCB Address 

Returned Value: 

Register A: 00H 



The Lock Record function is an MP/M II function that is supported under CP/M 3 
only to provide compatibility between CP/M 3 and MP/M. It is intended for use in 
situations where more than one running program has Read- Write access to a com- 
mon file. Because CP/M 3 is a single-user operating system in which only one pro- 
gram can run at a time, this situation cannot occur. Thus, under CP/M 3, Function 
42 performs no action except to return the value 00H in register A indicating that 
the record lock operation is successful. 
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BDOS FUNCTION 43: 


UNLOCK RECORD 


Entry Parameters: 
Registers C: 
DE: 

Returned Value: 

Register A: 


2BH 

FCB Address 

00H 



The Unlock Record function is an MP/M II function that is supported under 
CP/M 3 only to provide compatibility between CP/M 3 and MP/M. It is intended for 
use in situations where more than one running program has Read-Write access to a 
common file. Because CP/M 3 is a single-user operating system in which only one 
program can run at a time, this situation cannot occur. Thus, under CP/M 3, Func- 
tion 43 performs no action except to return the value 00H in register A indicating 
that the record unlock operation is successful. 
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BDOS FUNCTION 44: SET MULTI-SECTOR COUNT 



Entry Parameters: 

Registers C: 2CH 

E: Number of Sectors 

Returned Value: 

Register A: Return Code 



The Set Multi-Sector Count function provides logical record blocking under 
CP/M 3. It enables a program to read and write from 1 to 128 records of 128 bytes 
at a time during subsequent BDOS Read and Write functions. 

Function 44 sets the Multi-Sector Count value for the calling program to the value 
passed in register E. Once set, the specified Multi-Sector Count remains in effect until 
the calling program makes another Set Multi-Sector Count function call and changes 
the value. Note that the CCP sets the Multi-Sector Count to one when it initiates a 
transient program. 

The Multi-Sector Count affects BDOS error reporting for the BDOS Read and 
Write functions. If an error interrupts these functions when the Multi-Sector is greater 
than one, they return the number of records successfully read or written in register 
H for all errors except for physical errors (A = 255). 

Upon return, register A is set to zero if the specified value is in the range of 1 to 
128. Otherwise, register A is set to OFFH. 
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BDOS FUNCTION 45: SET BDOS ERROR MODE 



Entry Parameters: 

Registers C: 2DH 

E: BDOS Error Mode 

Returned Value: None 



Function 45 sets the BDOS error mode for the calling program to the mode speci- 
fied in register E. If register E is set to OFFH, 255 decimal, the error mode is set to 
Return Error mode. If register E is set to OFEH, 254 decimal, the error mode is set 
to Return and Display mode. If register E is set to any other value, the error mode is 
set to the default mode. 

The SET BDOS Error Mode function determines how physical and extended errors 
(see Section 2.2.13) are handled for a program. The Error Mode can exist in three 
modes: the default mode, Return Error mode, and Return and Display Error mode. 
In the default mode, the BDOS displays a system message at the console that identi- 
fies the error and terminates the calling program. In the return modes, the BDOS sets 
register A to OFFH, 255 decimal, places an error code that identifies the physical or 
extended error in register H and returns to the calling program. In Return and 
Display mode, the BDOS displays the system message before returning to the calling 
program. No system messages are displayed, however, when the BDOS is in Return 
Error mode. 
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BDOS FUNCTION 46: GET DISK FREE SPACE 



Entry Parameters: 
Registers C: 
E: 

Returned Value: 



Registers 



A: 
H: 



2EH 
Drive 

First 3 bytes 
of current DMA 
buffer 
Error Flag 
Physical Error 



The Get Disk Free Space function determines the number of free sectors, 128 byte 
records, on the specified drive. The calling program passes the drive number in 
register E, with for drive A, 1 for B, and so on, through 15 for drive P in a full 16- 
drive system. Function 46 returns a binary number in the first 3 bytes of the current 
DMA buffer. This number is returned in the following format: 



fsO 


fsl 


fs2 



Disk Free Space Field Format 

fsO = low byte 
fsl = middle byte 
fs2 = high byte 

Note that the returned free space value might be inaccurate if the drive has been 
marked Read-Only. 
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Upon return, register A is set to zero if the function is successful. However, if the 
BDOS Error Mode is one of the return modes (see Function 45), and a physical error 
is encountered, register A is set to OFFH, 255 decimal, and register H is set to one of 
the following values: 

01 - Disk I/O error 
04 - Invalid drive error 



3-66 



DIGITAL RESEARCH 1 



CP/M 3 Programmer's Guide 



3 BDOS Calls: Function 47 



BDOS FUNCTION 47: CHAIN TO PROGRAM 



Entry Parameters: 
Registers C: 
E: 



2FH 
Chain Flag 



The Chain To Program function provides a means of chaining from one program 
to the next without operator intervention. The calling program must place a com- 
mand line terminated by a null byte, 00H, in thejdefault DMA buffer. If register E is 
set to OFFH, the CCP initializes the default drive and user number to the current 
program values when it passes control to the specified transient program. Otherwise, 
these parameters are set to the default CCP values. Note that Function 108, Get/Set 
Program Return Code, can be used to pass a two byte value to the chained program. 

Function 47 does not return any values to the calling program and any encoun- 
tered errors are handled by the CCP. 
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BDOS FUNCTION 48: FLUSH BUFFERS 


Entry Parameters: 
Registers C: 
E: 


30H 
Purge Flag 


Returned Value: 




Registers A: 
H: 


Error Flag 
Physical Error 



The Flush Buffers function forces the write of any write-pending records contained 
in internal blocking/deblocking buffers. If register E is set to OFFH, this function also 
purges all active data buffers. Programs that provide write with read verify support 
need to purge internal buffers to ensure that verifying reads actually access the disk 
instead of returning data that is resident in internal data buffers. The CP/M 3 PIP 
utility is an example of such a program. 

Upon return, register A is set to zero if the flush operation is successful. If a 
physical error is encountered, the Flush Buffers function performs different actions 
depending on the BDOS error mode (see Function 45). If the BDOS error mode is in 
the default mode, a message identifying the error is displayed at the console and the 
calling program is terminated. Otherwise, the Flush Buffers function returns to the 
calling program with register A set to OFFH and register H set to the following 
physical error code: 

01 : Disk I/O error 

02 : Read/only disk 

04 : Invalid drive error 
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BDOS FUNCTION 49: 


GET / SET SYSTEM 
CONTROL BLOCK 


Entry Parameters: 
Registers C: 
DE: 

Returned Value: 
Registers A: 
HL: 


31H 

SCB PB Address 

Returned Byte 
Returned Word 



Function 49 allows access to parameters located in the CP/M 3 System Control 
Block (SCB). The SCB is a 100-byte data structure residing within the BDOS that 
contains flags and data used by the BDOS, CCP and other system components. Note 
that Function 49 is a CP/M 3 specific function. Programs intended for both MP/M II 
and CP/M 3 should either avoid the use of this function or isolate calls to this 
function in CP/M 3 version-dependent sections. 

To use Function 49, the calling program passes the address of a data structure 
called the SCB parameter block in register pair DE. This data structure identifies the 
byte or word of the SCB to be updated or returned. The SCB parameter block is 
defined as: 



SCBPB: 



DB OFFSET 
DB SET 



DW VALUE 



Offset within SCB 
OFFH if setting a byte 
OFEH if setting a word 
001H - OFDH are reserued 
000H if a Set operation 
Byte or word value to be 



set 



The OFFSET parameter identifies the offset of the field within the SCB to be updated 
or accessed. The SET parameter determines whether Function 49 is to set a byte or 
word value in the SCB or if it is to return a byte from the SCB. The VALUE 
parameter is used only in set calls. In addition, only the first byte of VALUE is 
referenced in set byte calls. 
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Use caution when you set SCB fields. Some of these parameters reflect the current 
state of the operating system. If they are set to invalid values, software errors can 
result. In general, do not use Function 49 to set a system parameter if another BDOS 
function can achieve the same result. For example, Function 49 can be called to 
update the Current DMA Address field within the SCB. This is not equivalent to 
making a Function 26, Set DMA Address call, and updating the SCB Current DMA 
field in this way would result in system errors. However, you can use Function 49 to 
return the Current DMA address. The System Control Block is summarized in the 
following table. Each of these fields is documented in detail in Appendix A. 





Table 3-4. System Control Block 


Offset 


Description 


00 — 


04 


Reserved For System Use 


05 




BDOS version number 


06 — 


09 


User Flags 


OA — 


OF 


Reserved For System Use 


10 — 


11 


Program Error return code 


12 — 


19 


Reserved For System Use 


1A 




Console Width (columns) 


IB 




Console Column Position 


1C 




Console Page Length 


ID — 


21 


Reserved For System Use 


22 — 


23 


CONIN Redirection flag 


24 — 


25 


CONOUT Redirection flag 


26 — 


27 


AUXIN Redirection flag 


28 — 


29 


AUXOUT Redirection flag 


2A — 


2B 


LSTOUT Redirection flag 


2C 




Page Mode 


2D 




Reserved For System Use 


2E 




CTRL-H Active 


2F 




Rubout Active 


30 — 


32 


Reserved For System Use 


33 — 


34 


Console Mode 


35 — 


36 


Reserved For System Use 


37 




Output Delimiter 


38 




List Output Flag 


39 — 


■ 3B 


Reserved For System Use 



3-70 



I DIGITAL RESEARCH 1 



CP/M 3 Programmer's Guide 



3 BDOS Calls: Function 49 



Table 3-4. (continued) 



Offt 


>et 


Description 


3C — 


3D 


Current DMA Address 


3E 




Current Disk 


3F — 


43 


Reserved For System Use 


44 




Current User Number 


45 — 


49 


Reserved For System Use 


4A 




BDOS Multi-Sector Count 


4B 




BDOS Error Mode 


4C — 


4F 


Drive Search Chain (DISKS A:,E:,F:) 


50 




Temporary File Drive 


51 




Error Disk 


52 — 


56 


Reserved For System Use 


57 




BDOS flags 


58 — 


5C 


Date Stamp 


5D — 


5E 


Common Memory Base Address 


5F — 


63 


Reserved For System Use 



If Function 49 is called with the OFFSET parameter of the SCB parameter block 
greater than 63 H, the function performs no action but returns with registers A and 
HL set to zero. 
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BDOS FUNCTION 50: DIRECT BIOS CALLS 



Entry Parameters: 

Registers C: 32H 

DE: BIOS PB Address 

Returned Value: BIOS RETURN 



Function 50 provides a direct BIOS call through the BDOS to the BIOS. The 
calling program passes the address of a data structure called the BIOS Parameter 
Block (BIOSPB) in register pair DE. The BIOSPB contains the BIOS function number 
and register contents as shown below: 



BIOSPB 



db 


FUNC 


db 


AREG 


dw 


BCREG 


dw 


DEREG 


dw 


HLREG 



BIOS function no* 
A register contents 
BC register contents 
DE register contents 
HL register contents 



System Reset (Function 0) is equivalent to Function 50 with a BIOS function 
number of 1. 

Note that the register pair BIOSPB fields (BCREG, DEREG, HLREG) are defined 
in low byte, high byte order. For example, in the BCREG field, the first byte contains 
the C register value, the second byte contains the B register value. 

Under CP/M 3, direct BIOS calls via the BIOS jump vector are only supported for 
the BIOS Console I/O and List functions. You must use Function 50 to call any other 
BIOS functions. In addition, Function 50 intercepts BIOS Function 27 (Select Mem- 
ory) calls and returns with register A set to zero. Refer to the CP/M Plus (CP/M 
Version 3) Operating System System Guide for the definition of the BIOS functions 
and their register passing and return conventions. 
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BDOS FUNCTION 59: LOAD OVERLAY 


Entry Parameters: 
Registers C: 
DE: 

Returned Value: 
Registers A: 
H: 


3BH 

FCB Address 

Error Code 
Physical Error 



Only transient programs with an RSX header can use the Load Overlay function 
because BDOS Function 59 is supported by the LOADER module. The calling pro- 
gram must have a header to force the LOADER to remain resident after the program 
is loaded (see Section 1.3). 

Function 59 loads either an absolute or relocatable module. Relocatable modules 
are identified by a filetype of PRL. Function 59 does not call the loaded module. 

The referenced FCB must be successfully opened before Function 59 is called. The 
load address is specified in the first two random record bytes of the FCB, rO and rl. 
The LOADER returns an error if the load address is less than 100H, or if performing 
the requested load operation would overlay the LOADER, or any other Resident 
System Extensions that have been previously loaded. 

When loading relocatable files, the LOADER requires enough room at the load ad- 
dress for the complete PRL file including the header and bit map (see Appendix B). 
Otherwise an error is returned. Function 59 also returns an error on PRL file load 
requests if the specified load address is not on a page boundary. 

Upon return, Function 59 sets register A to zero if the load operation is successful. 
If the LOADER RSX is not resident in memory because the calling program did not 
have a RSX header, the BDOS returns with register A set to OFFH and register H set 
to zero. If the LOADER detects an invalid load address, or if insufficient memory is 
available to load the overlay, Function 59 returns with register A set to OFEH. All 
other error returns are consistent with the error codes returned by BDOS Function 
20, Read Sequential. 
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BDOS FUNCTION 60: CALL RESIDENT SYSTEM 

EXTENSION 


Entry Parameters: 
Registers C: 
DE: 

Returned Value: 
Registers A: 
H: 


3CH 

RSX PB Address 

Error Code 
Physical Error 



Function 60 is a special BDOS function that you use when you call Resident 
System Extensions. The RSX subfunction is specified in a structure called the RSX 
Parameter Block, defined as follows: 



RSXPB 



db FUNC 5 

db NUMPARMS 5 

dw PARMETER1 5 

dw PARMETER2 5 



RSX Function number 
Number of word parameters 
Parameter 1 
Parameter 2 



dw PARMETERn > Parameter n 

RSX modules filter all BDOS calls and capture RSX function calls that they can 
handle. If there is no RSX module present in memory that can handle a specific RSX 
function call, the call is not trapped, and the BDOS returns OFFH in registers A and 
L. RSX function numbers from to 127 are available for CP/M 3 compatible soft- 
ware use. RSX function numbers 128 to 255 are reserved for system use. 
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BDOS FUNCTION 98 : FREE BLOCKS 



Entry Parameters: 

Register C: 62H 

Returned Value: 

Registers A: Error Flag 

H: Physical Error 



The Free Blocks function scans all the currently logged-in drives, and for each 
drive returns to free space all temporarily-allocated data blocks. A temporarily-allo- 
cated data block is a block that has been allocated to a file by a BDOS write 
operation but has not been permanently recorded in the directory by a BDOS close 
operation. The CCP calls Function 98 when it receives control following a system 
warm start. Be sure to close your file, particularly any file you have written to, prior 
to calling Function 98. 

In the nonbanked version of CP/M 3, Function 98 frees only temporarily allocated 
blocks for systems that request double allocation vectors in GENCPM. 

Upon return, register A is set to zero if Function 98 is successful. If a physical 
error is encountered, the Free Blocks function performs different actions depending 
on the BDOS error mode (see Function 45). If the BDOS error mode is in the default 
mode, a message identifying the error is displayed at the console and the calling 
program is terminated. Otherwise, the Free Blocks function returns to the calling 
program with register A set to OFFH and register H set to the following physical 
error code: 

04 : Invalid drive error 



DIGITAL RESEARCH 1 



3-75 



3 BDOS Calls: Function 99 



CP/M 3 Programmer's Guide 



BDOS FUNCTION 99: 


TRUNCATE FILE 


Entry Parameters: 






Registers C: 


63H 




DE: 


FCB Address 


Returned Value: 






Registers A: 


Directory 


Code 


H: 


Extended 


or Physical Error 



The Truncate File function sets the last record of a file to the random record 
number contained in the referenced FCB. The calling program passes the address of 
the FCB in register pair DE, with byte of the FCB specifying the drive, bytes 1 
through 11 specifying the filename and filetype, and bytes 33 through 35, rO, rl, and 
r2, specifying the last record number of the file. The last record number is a 24 bit 
value, stored with the least significant byte first, rO, the middle byte next, rl, and the 
high byte last, r2. This value can range from to 262,143, which corresponds to a 
maximum value of 3 in byte r2. 

If the file specified by the referenced FCB is password protected, the correct pass- 
word must be placed in the first eight bytes of the current DMA buffer, or have been 
previously established as the default password (see Function 106). 

Function 99 requires that the file specified by the FCB not be open, particularly if 
the file has been written to. In addition, any activated FCBs naming the file are not 
valid after Function 99 is called. Close your file before calling Function 99, and then 
reopen it after the call to continue processing on the file. 
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Function 99 also requires that the random record number field of the referenced 
FCB specify a value less than the current file size. In addition, if the file is sparse, the 
random record field must specify a record in a region of the file where data exists. 

Upon return, the Truncate function returns a Directory Code in register A with the 
value if the Truncate function is successful, or OFFH, 255 decimal, if the file is not 
found or the record number is invalid. Register H is set to zero in both of these 
cases. If a physical or extended error is encountered, the Truncate function performs 
different actions depending on the BDOS error mode (see Function 45). If the BDOS 
error mode is in the default mode, a message identifying the error is displayed at the 
console and the program is terminated. Otherwise, the Truncate function returns to 
the calling program with register A set to OFFH and register H set to one of the 
following physical or extended error codes: 

01 : Disk I/O error 

02 : Read-Only disk 

03 : Read-Only file 

04 : Invalid drive error 
07 : File password error 

09 : ? in filename or filetype field 
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BDOS FUNCTION 100: SET DIRECTORY LABEL 


Entry Parameters: 
Registers C: 
DE: 

Returned Value: 

Registers A: 

H: 


64H 

FCB Address 

Directory Code 

Physical or Extended Error 



The Set Directory Label function creates a directory label, or updates the existing 
directory label for the specified drive. The calling program passes in register pair DE 
the address of an FCB containing the name, type, and extent fields to be assigned to 
the directory label. The name and type fields of the referenced FCB are not used to 
locate the directory label in the directory; they are simply copied into the updated or 
created directory label. The extent field of the FCB, byte 12, contains the user's 
specification of the directory label data byte. The definition of the directory label 
data byte is: 

bit 7 - Require passwords for password-protected files 
(Not supported in nonbanked CP/M 3 systems) 
6 - Perform access date and time stamping 
5 - Perform update date and time stamping 
4 - Perform create date and time stamping 
- Assign a new password to the directory label 

If the current directory label is password protected, the correct password must be 
placed in the first eight bytes of the current DMA, or have been previously estab- 
lished as the default password (see Function 106). If bit 0, the low-order bit, of byte 
12 of the FCB is set to 1, it indicates that a new password for the directory label has 
been placed in the second eight bytes of the current DMA. 

Note that Function 100 is implemented as an RSX, DIRLBL.RSX, in nonbanked 
CP/M 3 systems. If Function 100 is called in nonbanked systems when the DIRLBL.RSX 
is not resident, an error code of 0FFH is returned. 
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Function 100 also requires that the referenced directory contain SFCBs to activate 
date and time stamping on the drive. If an attempt is made to activate date and time 
stamping when no SFCBs exist, Function 100 returns an error code of 0FFH in 
register A and performs no action. The CP/M 3 INITDIR utility initializes a directory 
for date and time stamping by placing an SFCB record in every fourth entry of the 
directory. 

Function 100 returns a Directory Code in register A with the value if the direc- 
tory label create or update is successful, or 0FFH, 255 decimal, if no space exists in 
the referenced directory to create a directory label, or if date and time stamping was 
requested and the referenced directory did not contain SFCBs. Register H is set to 
zero in both of these cases. If a physical error or extended error is encountered, 
Function 100 performs different actions depending on the BDOS error mode (see 
Function 45). If the BDOS error mode is the default mode, a message identifying the 
error is displayed at the console and the calling program is terminated. Otherwise, 
Function 100 returns to the calling program with register A set to 0FFH and register 
H set to one of the following physical or extended error codes: 

01 : Disk I/O error 

02 : Read-Only disk 
04 : Invalid drive error 
07 : File password error 
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BDOS FUNCTION 101: 



RETURN DIRECTORY 
LABEL DATA 



Entry Parameters: 

Registers C: 65H 

E: Drive 

Returned Value: 

Registers A: Directory Label 
Data Byte 

H: Physical Error 



The Return Directory Label Data function returns the data byte of the directory 
label for the specified drive. The calling program passes the drive number in register 
E with for drive A, 1 for drive B, and so on through 15 for drive P in a full sixteen 
drive system. The format of the directory label data byte is shown below: 

bit 7 - Require passwords for password protected files 
6 - Perform access date and time stamping 
5 - Perform update date and time stamping 
4 - Perform create date and time stamping 
- Directory label exists on drive 

Function 101 returns the directory label data byte to the calling program in register 
A. Register A equal to zero indicates that no directory label exists on the specified 
drive. If a physical error is encountered by Function 101 when the BDOS Error mode 
is in one of the return modes (see Function 45), this function returns with register A 
set to OFFH, 255 decimal, and register H set to one of the following: 

01 : Disk I/O error 
04 : Invalid drive error 
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BDOS FUNCTION 102: READ FILE DATE STAMPS 

AND PASSWORD MODE 


Entry Parameters: 
Registers C: 
DE: 

Returned Value: 

Registers A: 

H: 


66H 

FCB Address 

Directory Code 
Physical Error 



Function 102 returns the date and time stamp information and password mode for 
the specified file in byte 12 and bytes 24 through 32 of the specified FCB. The calling 
program passes in register pair DE, the address of an FCB in which the drive, file- 
name, and filetype fields have been defined. 

If Function 102 is successful, it sets the following fields in the referenced FCB: 

byte 12 : Password mode field 
bit 7 - Read mode 
bit 6 - Write mode 
bit 4 - Delete mode 

Byte 12 equal to zero indicates the file has not been assigned a password. In non- 
banked systems, byte 12 is always set to zero. 

byte 24 - 27 : Create or Access time stamp field 
byte 28-31 : Update time stamp field 

The date stamp fields are set to binary zeros if a stamp has not been made. The 
format of the time stamp fields is the same as the format of the date and time 
structure described in Function 104. 
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Upon return, Function 102 returns a Directory Code in register A with the value 
zero if the function is successful, or OFFH, 255 decimal, if the specified file is not 
found. Register H is set to zero in both of these cases. If a physical or extended error 
is encountered, Function 102 performs different actions depending on the BDOS 
error mode (see Function 45). If the BDOS error mode is in the default mode, a 
message identifying the error is displayed at the console and the calling program is 
terminated. Otherwise, Function 102 returns to the calling program with register A 
set to OFFH and register H set to one of the following physical or extended error 
codes: 

01 : Disk I/O error 

04 : Invalid drive error 

09 : ? in filename or filetype field 
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BDOS FUNCTION 103: WRITE FILE XFCB 



Entry Parameters: 

Registers C: 67H 

DE: FCB Address 



Returned Value: 

Registers A: 

H: 



Directory Code 
Physical Error 



The Write File XFCB function creates a new XFCB or updates the existing XFCB 
for the specified file. The calling program passes in register pair DE the address of an 
FCB in which the drive, name, type, and extent fields have been defined. The extent 
field specifies the password mode and whether a new password is to be assigned to 
the file. The format of the extent byte is shown below: 

FCB byte 12 (ex) : XFCB password mode 

bit 7 - Read mode 

bit 6 - Write mode 

bit 5 - Delete mode 

bit - Assign new password to the file 

If the specified file is currently password protected, the correct password must reside 
in the first eight bytes of the current DMA, or have been previously established as 
the default password (see Function 106). If bit is set to 1, the new password must 
reside in the second eight bytes of the current DMA. 
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Upon return, Function 103 returns a Directory Code in register A with the value 
zero if the XFCB create or update is successful, or OFFH, 255 decimal, if no directory 
label exists on the specified drive, or the file named in the FCB is not found, or no 
space exists in the directory to create an XFCB. Function 103 also returns with OFFH 
in register A if passwords are not enabled by the referenced directory's label. On 
nonbanked systems, this function always returns with register A = OFFH because 
passwords are not supported. Register H is set to zero in all of these cases. If a 
physical or extended error is encountered, Function 103 performs different actions 
depending on the BDOS error mode (see Function 45). If the BDOS error mode is 
the default mode, a message identifying the error is displayed at the console and the 
calling program is terminated. Otherwise, Function 103 returns to the calling pro- 
gram with register A set to OFFH and register H set to one of the following physical 
or extended error codes: 

01 : Disk I/O error 

02 : Read-Only disk 
04 : Invalid drive error 
07 : File password error 

09 : ? in filename or filetype field 
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BDOS FUNCTION 104: SET DATE AND TIME 



Entry Parameters: 

Registers C: 68H 

DE: DAT Address 

Returned Value: none 



The Set Date and Time function sets the system internal date and time. The calling 
program passes the address of a 4-byte structure containing the date and time speci- 
fication in the register pair DE. The format of the date and time (DAT) data structure 
is: 



byte - 1 
byte 2 
byte 3 



Date field 
Hour field 
Minute field 



The date is represented as a 16-bit integer with day 1 corresponding to January 1, 
1978. The time is represented as two bytes: hours and minutes are stored as two 
BCD digits. 

This function also sets the seconds field of the system date and time to zero. 
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BDOS FUNCTION 105: GET DATE AND TIME 


Entry Parameters: 
Registers C: 
DE: 

Returned Value: 
Register A: 
DAT set 


69H 

DAT Address 

seconds 



The Get Date and Time function obtains the system internal date and time. The 
calling program passes in register pair DE, the address of a 4-byte data structure 
which receives the date and time values. The format of the date and time, DAT, data 
structure is the same as the format described in Function 104. Function 105 also 
returns the seconds field of the system date and time in register A as a two digit BCD 
value. 
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BDOS FUNCTION 106: SET DEFAULT PASSWORD 



Entry Parameters: 

Registers C: 6AH 

DE: Password Address 

Returned Value: none 



The Set Default Password function allows a program to specify a password value 
before a file protected by the password is accessed. When the file system accesses a 
password-protected file, it checks the current DMA, and the default password for the 
correct value. If either value matches the file's password, full access to the file is 
allowed. Note that this function performs no action in nonbanked CP/M 3 systems 
because file passwords are not supported. 

To make a Function 106 call, the calling program sets register pair DE to the 
address of an 8-byte field containing the password. 
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BDOS FUNCTION 107: RETURN SERIAL NUMBER 



Entry Parameters: 

Registers C: 6BH 

DE: Serial Number Field 

Returned Value: Serial number field set 



Function 107 returns the CP/M 3 serial number to the 6-byte field addressed by 
register pair DE. 
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BDOS FUNCTION 108: GET/SET PROGRAM RETURN 




CODE 




Entry Parameters: 






Registers C: 


6CH 




DE: 


OFFFFH (Get) or 
Program Return Code (Set) 




Returned Value: 






Register HL: 


Program Return Code or (no 


value) 



CP/M 3 allows programs to set a return code before terminating. This provides a 
mechanism for programs to pass an error code or value to a following job step in 
batch environments. For example, Program Return Codes are used by the CCP in 
CP/M 3's conditional command line batch facility. Conditional command lines are 
command lines that begin with a colon, :. The execution of a conditional command 
depends on the successful execution of the preceding command. The CCP tests the 
return code of a terminating program to determine whether it successfully completed 
or terminated in error. Program return codes can also be used by programs to pass 
an error code or value to a chained program (see Function 47, Chain To Program). 

A program can set or interrogate the Program Return Code by calling Function 
108. If register pair DE = OFFFFH, then the current Program Return Code is returned 
in register pair HL. Otherwise, Function 108 sets the Program Return Code to the 
value contained in register pair DE. Program Return Codes are defined in Table 3-5. 
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Table 3-5. Program Return Codes 



Code 


Meaning 


0000 — FEFF 


Successful return 


FF00 — FFFE 


Unsuccessful return 


0000 


The CCP initializes the Program Return Code to zero unless 
the program is loaded as the result of program chain. 


FF80 — FFFC 


Reserved 


FFFD 


The program is terminated because of a fatal BDOS error. 


FFFE 


The program is terminated by the BDOS because the user 
typed a CTRL-C. 
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BDOS FUNCTION 109: GET/SET CONSOLE MODE 



Entry Parameters: 

Registers C: 6DH 

DE: OFFFFH (Get) or Console Mode (Set) 

Returned Value: 
Register HL: Console Mode or (no value) 



A program can set or interrogate the Console Mode by calling Function 109. If 
register pair DE = OFFFFH, then the current Console Mode is returned in register 
HL. Otherwise, Function 109 sets the Console Mode to the value contained in regis- 
ter pair DE. 

The Console Mode is a 16-bit system parameter that determines the action of 
certain BDOS Console I/O functions. The definition of the Console Mode is: 

bit = 1 - CTRL-C only status for Function 11. 
= - Normal status for Function 11. 

bit 1 = 1- Disable stop scroll, CTRL-S, start scroll, CTRL-Q, support. 
= - Enable stop scroll, start scroll support. 

bit 2 = 1 - Raw console output mode. Disables tab expansion for Functions 2, 
9 and 111. Also disables printer echo, CTRL-P, support. 
= - Normal console output mode. 

bit 3 = 1- Disable CTRL-C program termination 
= - Enable CTRL-C program termination 
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bits 8,9 - Console status mode for RSXs that perform console input redirec- 
tion from a file. These bits determine how the RSX responds to 
console status requests. 

bit 8 = 0, bit 9 = - conditional status 

bit 8 = 0, bit 9 = 1 - false status 

bit 8 = 1, bit 9 = - true status 

bit 8 = 1, bit 9 = 1 - bypass redirection 

Note that the Console Mode bits are numbered from right to left. 

The CCP initializes the Console Mode to zero when it loads a program unless the 
program has an RSX that overrides the default value. Refer to Section 2.2.1 for 
detailed information on Console Mode. 
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BDOS FUNCTION 110: GET/SET OUTPUT DELIMITER 



Entry Parameters: 
Registers C: 
DE: 
E: 



6EH 

OFFFFH (Get) or 

Output Delimiter (Set) 



Returned Value: 

Register A: Output Delimiter or (no value) 



A program can set or interrogate the current Output Delimiter by calling Function 
110. If register pair DE = OFFFFH, then the current Output Delimiter is returned in 
register A. Otherwise, Function 110 sets the Output Delimiter to the value contained 
in register E. 

Function 110 sets the string delimiter for Function 9, Print String. The default 
delimiter value is a dollar sign, $. The CCP restores the Output Delimiter to the 
default value when a transient program is loaded. 
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BDOS FUNCTION 111: PRINT BLOCK 



Entry Parameters: 

Registers C: 6FH 

DE: CCB Address 

Returned Value: none 



The Print Block function sends the character string located by the Character Con- 
trol Block, CCB, addressed in register pair DE, to the logical console, CONOUT:. If 
the Console Mode is in the default state (see Section 2.2.1), Function 111 expands 
tab characters, CTRL-I, in columns of eight characters. It also checks for stop scroll, 
CTRL-S, start scroll, CTRL-Q, and echoes to the logical list device, LST:, if printer 
echo, CTRL-P, has been invoked. 

The CCB format is: 

byte - 1 : Address of character string (word value) 
byte 2 - 3 : Length of character string (word value) 
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BDOS FUNCTION 112: LIST BLOCK 



Entry Parameters: 

Registers C: 70H 

DE: CCB Address 

Returned Value: none 



The List Block function sends the character string located by the Character Control 
Block, CCB, addressed in register pair DE, to the logical list device, LST:. 

The CCB format is: 

byte - 1 : Address of character string (word value) 
byte 2 - 3 : Length of character string (word value) 
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BDOS FUNCTION 152: PARSE FILENAME 



Entry Parameters: 

Registers C: 98H 

DE: PFCB Address 

Returned Value: 
Register HL: Return code 
Parsed file control block 



The Parse Filename function parses an ASCII file specification and prepares a File 
Control Block, FCB. The calling program passes the address of a data structure called 
the Parse Filename Control Block, PFCB, in register pair DE. The PFCB contains the 
address of the input ASCII filename string followed by the address of the target FCB 
as shown below: 



PFC6: DW INPUT 
DW FCB 



i Address of input ASCII strinsf 
5 Address of tar-Set FCB 



The maximum length of the input ASCII string to be parsed is 128 bytes. The target 
FCB must be 36 bytes in length. 

Function 152 assumes the input string contains file specifications in the following 
form: 

{d:}filename{.typ}{;password} 

where items enclosed in curly brackets are optional. Function 152 also accepts iso- 
lated drive specifications d: in the input string. When it encounters one, it sets the 
filename, filetype, and password fields in the FCB to blank. 
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The Parse Filename function parses the first file specification it finds in the input 
string. The function first eliminates leading blanks and tabs. The function then assumes 
that the file specification ends on the first delimiter it encounters that is out of 
context with the specific field it is parsing. For instance, if it finds a colon, and it is 
not the second character of the file specification, the colon delimits the entire file 
specification. 

Function 152 recognizes the following characters as delimiters: 

space 

tab 

return 

null 

; (semicolon) - except before password field 

= (equal) 

< (less than) 

> (greater than) 

. (period) - except after filename and before filetype 

: (colon) - except before filename and after drive 

, (comma) 

| (vertical bar) 

[ (left square bracket) 

] (right square bracket) 

If Function 152 encounters a non-graphic character in the range 1 through 31 not 
listed above, it treats the character as an error. The Parse Filename function initializes 
the specified FCB shown in Table 3-6. 
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Table 3-6. FCB Format 



Location 



Contents 



byte 



byte 1-8 



byte 9-11 



byte 12-15 
byte 16-23 



byte 24-31 



The drive field is set to the specified drive. If the drive is not 
specified, the default drive code is used. = default, 1 = A, 
2 = B. 

The name is set to the specified filename. All letters are con- 
verted to upper-case. If the name is not eight characters long, 
the remaining bytes in the filename field are padded with blanks. 
If the filename has an asterisk, *, all remaining bytes in the 
filename field are filled in with question marks, ?. An error 
occurs if the filename is more than eight bytes long. 

The type is set to the specified filetype. If no filetype is speci- 
fied, the type field is initialized to blanks. All letters are con- 
verted to upper-case. If the type is not three characters long, 
the remaining bytes in the filetype field are padded with blanks. 
If an asterisk, *, occurs, all remaining bytes are filled in with 
question marks, ?. An error occurs if the type field is more 
than three bytes long. 

Filled in with zeros. 

The password field is set to the specified password. If no pass- 
word is specified, it is initialized to blanks. If the password is 
less than eight characters long, remaining bytes are padded 
with blanks. All letters are converted to upper-case. If the pass- 
word field is more than eight bytes long, an error occurs. Note 
that a blank in the first position of the password field implies 
no password was specified. 

Reserved for system use. 
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If an error occurs, Function 152 returns an OFFFFH in register pair HL. 

On a successful parse, the Parse Filename function checks the next item in the 
input string. It skips over trailing blanks and tabs and looks at the next character. If 
the character is a null or carriage return, it returns a indicating the end of the input 
string. If the character is a delimiter, it returns the address of the delimiter. If the 
character is not a delimiter, it returns the address of the first trailing blank or tab. 

If the first non-blank or non-tab character in the input string is a null, 0, or 
carriage return, the Parse Filename function returns a zero indicating the end of 
string. 

If the Parse Filename function is to be used to parse a subsequent file specification 
in the input string, the returned address must be advanced over the delimiter before 
placing it in the PFCB. 



End of Section 3 
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Section 4 
Programming Examples 



The programs presented in this section illustrate how to use the BDOS functions 
described in the previous section. The examples show how to copy a file, how to 
dump a file, how to create or access a random access file, and how to write an RSX 
program. 



4.1 A Sample File-To-File Copy Program 

The following program illustrates simple file operations. You can create the pro- 
gram source file, COPY.ASM, using ED or another editor, and then assemble 
COPY. ASM using MAC™. MAC produces the file COPY.HEX. Use the utility 
HEXCOM to produce a COPY.COM file that can execute under CP/M 3. 

The COPY program first sets the stack pointer to a local area, then moves the 
second name from the default area at 006CH to a 33-byte file control block named 
DFCB. The DFCB is then prepared for file operations by clearing the current record 
field. Because the CCP sets up the source FCB at 005 CH upon entry to the COPY 
program, the source and destination FCBs are now ready for processing. To prepare 
the source FCB, the CCP places the first name into the default FCB, with the proper 
fields zeroed, including the current record field at 007CH. 

COPY continues by opening the source file, deleting any existing destination file, 
and then creating the destination file. If each of these operations is successful, the 
COPY program loops at the label COPY until each record is read from the source 
file and placed into the destination file. Upon completion of the data transfer, the 
destination file is closed, and the program returns to the CCP command level by 
jumping to BOOT. 
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sample file-to-file copy program 

at the ccp levelt the command 

copy a: x . y b :u. v 

copies the file nanied x»y from drive 
a to a file named u.v on drive b. 



0000 


= 




boot 


equ 


OOOOh 


system reboot 


0005 


= 




bdos 


equ 


0005h 


bdos entry point 


005c 


= 




fcbl 


equ 


005ch 


first file name 


005c 


= 




sfcb 


equ 


fcbl 


source fob 


OOBc 


= 




fcb2 


equ 


006ch 


second file name 


0080 


= 




dbuff 


equ 


0080h 


default buffer 


0100 


= 




tpa 


equ 


OlOOh 


beflinnins of tpa 


0009 


= 




printf 


equ 


9 


print buffer func# 


OOOf 


= 




openf 


equ 


15 


open file func* 


0010 


= 




closef 


equ 


16 


close file func* 


0013 


= 




deletef 


equ 


19 


delete file func* 


0014 


= 




readf 


equ 


20 


sequential read 


0015 


= 




writef 


equ 


21 


sequential write 


0016 


= 




makef 


equ 


22 


make file func* 


0100 






? 


o ra 


tpa 


besinnins" of tpa 


0100 


311b02 




lxi 


sp fStack 


local stack 








5 


move 


second file 


name to dfcb 


0103 


OelO 






mvi 


c»16 


half an fcb 


0105 


116c 


00 




lxi 


d»fcb2 


source of move 


0108 


21da 


01 




lxi 


h.dfcb 


destination fcb 


010b 


la 




mfcb: 


ldax 


d 


» source fcb 


010c 


13 






inx 


d 


ready next 


OlOd 


77 






MOM 


m >a 


dest fcb 


OlOe 


23 






inx 


h 


i ready next 


OlOf 


Od 






dc r 


c 


count 16. . .0 


0110 


c20b01 




Jnz 


mfcb 


! loop 16 times 








! 


name 


has been mo 


jed t zero c r 


0113 


af 






x ra 


a 


» a = OOh 


0114 


32fa 


01 




sta 


df cbc r 


! current rec = 
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source and destination fobs ready 



0117 


115c00 


lxi 


011a 


cd6901 


call 


Olid 


118701 


lxi 


0120 


3c 


in r 


0121 


ccBlOl 

5 
5 


cz 
sour 


0124 


lldaOl 


lxi 


0127 


cd7301 


call 


012a 


i 
lldaOl 


lxi 


012d 


cd8201 


call 


0130 


119601 


lxi 


0133 


3c 


in r 


0134 


ccGlOl 


cz 



d » s f cb 5 source file 

open 5 error if 255 

d»nofile5 ready message 

a 5 255 becomes 

finis ! done if no file 



source file open* prep destination 
d >df cb ! destination 
delete i remove if present 



d »df cb 5 destination 

make 5 create the file 

d»nodir 5 ready message 

a 5 255 becomes 

finis i done if no dir space 



source file open t dest file open 
copy until end of file on source 



0137 


115c00 copy: 


lxi 


d »sf cb 


source 


013a 


cd7801 


call 


read 


read next record 


013d 


b7 


o ra 


a 


end of file? 


013e 


c25101 


Jnz 


eof i le 


skip write if so 




5 


not en 


d of filet 


write the record 


0141 


lldaOl 


lxi 


d tdfcb 


destination 


0144 


cd7d01 


call 


write 


write record 


0147 


1U901 


lxi 


d >space 


ready message 


014a 


b7 


o ra 


a 


00 if write ok 


014b 


C46101 


cnz 


finis 


end if so 


014e 


c33701 


Jmp 


copy 


loop until eof 




eof i le : 


! end 


of filet cl 


ose destination 


0151 


lldaOl 


lxi 


d »dfcb 


destination 


0154 


cdGeOl 


cal 1 


close 


255 if error 


0157 


21bb01 


lxi 


h twrprct 


ready message 


015a 


3c 


in r 


a 


255 becomes 00 


015b 


ccGlOl 


cz 


finis 


should not happen 



015e llccOl 



copy operation complete* end 
lxi dtnormal! ready message 



finis: 5 write message giuen by de > reboot 

0161 0e09 mui ctPrintf 

0163 cd0500 call bdos ! write message 

0166 c30000 Jmp boot 5 reboot system 
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system interface subroutines 
(all return directly from bdos) 



0169 


OeOf 


open s 


fiwi 


c f openf 


016b 


C30500 




JfltP 


bdos 


016e 


OelO 


close : 


MMi 


c »closef 


0170 


c30500 




JftlP 


bdos 


0173 


0el3 


delete : 


mui 


c *deletef 


0175 


C30500 




Jmp 


bdos 


0178 


Oeia 


i 

read : 


mui 


c t readf 


017a 


C30500 




Jmp 


bdos 


017d 


0el5 


write : 


my i 


c »wri tef 


017f 


c30500 




Jmp 


bdos 


0182 


OelB 


> 

Make : 


mui 


c xnakef 


0184 


C30500 


5 
5 


Jmp 
conso 


bdos 
le messages 


0187 


6e6f20f 


*nof ile: 


db 


'no source file*' 


0196 


6e6f209nodi r: 


db 


'no directory space$' 


01a9 


Gf75741 


'space : 


db 


'out of data space*' 


Olbb 


7772695wrprot: 


db 


'write protected?*' 


Olcc 


636f700normal : 


db 


'copy complete*' 






5 


data 


areas 


Olda 




dfcb: 


ds 


33 5 destination fob 


Olfa 


= 


df cbc r 


equ 


dfcb+32 5 current record 


Olfb 




i 

stack : 


ds 


32 i 16 level stack 


021b 






end 





Note that this program makes several simplifications and could be enhanced. First, 
it does not check for invalid filenames that could, for example, contain ambiguous 
references. This situation could be detected by scanning the 32-byte default area 
starting at location 005 CH for ASCII question marks. To check that the filenames 
have, in fact, been included, COPY could check locations 005DH and 006DH for 
nonblank ASCII characters. Finally, a check should be made to ensure that the source 
and destination filenames are different. Speed could be improved by buffering more 
data on each read operation. For example, you could determine the size of memory 
by fetching FBASE from location 0006H, and use the entire remaining portion of 
memory for a data buffer. You could also use CP/M 3's Multi-Sector I/O facility to 
read and write data in up to 16K units. 
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4.2 A Sample File Dump Utility 

The following dump program reads an input file specified in the CCP command 
line, and then displays the content of each record in hexadecimal format at the 
console. 

5 DUMP program reads input file and displays hex data 



0100 






o rS 


lOOh 




0005 


= 


bdos 


eiu 


0005h 


5dos entry point 


0001 


= 


cons 


e«iu 


1 


iread console 


0002 


= 


typef 


eiu 


2 


5type function 


0009 


= 


printf 


eiu 


9 


ibuffer print entry 


000b 


= 


brkf 


equ 


11 


ibreak key function (true if char 


OOOf 


= 


openf 


esu 


15 


!file open 


0014 


= 


readf 


equ 


20 


iread function 


005c 


= 


fob 


eiu 


5ch 


ifile control block address 


0080 


= 


buff 


equ 


80h 


!input disk buffer address 








non 


Graphic characters 


OOOd 


= 


cr 


e«»u 


Odh 


icarriase return 


000a 


= 


If 


e<=iu 


Oah 


iline feed 






5 


file 


control bl 


ock definitions 


005c 


= 


f cbdn 


e«?u 


fcb+0 


idisk name 


005d 


= 


fcbfn 


eiu 


fcb + 1 


ifile name 


00G5 


= 


fcbft 


equ 


fcb+9 


idisk file type (3 characters) 


0068 


= 


fcbrl 


equ 


fcb+12 


ifile's current reel number 


006b 


= 


f cb re 


equ 


fcb+15 


ifile's record count (0 to 128) 


007c 


= 


f cbc r 


enu 


fcb+32 


icurrent (next) record number (0 


007d 




fcbln 

5 

5 


equ 
set 


fcb+33 
up stack 


5fcb lenSth 


0100 


210000 




lxi 


h.O 




0103 


39 




dad 


SP 








! 


entry stack pointer in hi from the ccp 


0104 


221502 




shld 


oldsp 








1 


set 


sp to local 


stack area (restored at finis) 


0107 


315702 




lxi 


sp»stkt 


OP 






5 


read 


and print 


successiue buffers 


010a 


cdclOl 




call 


setup 


!set up input file 


OlOd 


feff 




cpi 


255 


5255 if file not present 


OlOf 


c21b01 




Jnz 


openok 


iskip if open is ok 
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0112 llf301 
0115 cd9c01 
0118 C35101 



file not there* Sive error message and return 

lxi d »opnms3 

call err 

jhip finis 5to return 



openoK: 5open operation oK> set buffer index to end 

011b 3e80 MMi a >B0h 

Olid 321302 sta ibp 5set buffer pointer to 80h 

! hi contains next address to print 

0120 210000 lxi h »0 ?start with 0000 



Sloop: 



0123 e5 

0124 cda201 

0127 el 

0128 da5101 
012b 47 



012c 7d 
012d eGOf 
012f c24401 

0132 cd7201 



isave line posit ion 



i reoal 1 line position 

Scarry set by Snb if end file 



push h 

call sfnb 

pop h 

Jc finis 

mov b >a 

print hex values 

check fori ine fold 

mo u a >1 

ani Ofh »check low 4 bits 

Jnz nonum 

print line number 

call crlf 



0135 cd5901 

0138 Of 

0139 da5101 
5 013c 7c 
013d cd8f01 

0140 7d 

0141 cd8f01 



check for break key 

call break 

accum lsb = 1 if character ready 



rrc 

Jc 

mov 

call 

MOV 

call 



finis 
a »h 
phex 
a»l 
phex 



iinto carry 

ido not print any wore 



0144 23 

0145 3e20 
0147 cdG501 
014a 78 
014b cd8f01 
014e C32301 



mx 

fnvi 

call 

mov 

call 

Jmp 



h 

a » ' ' 

pchar 

a >b 

phex 

Sloop 



5to next line number 
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finis; 



0151 cd7201 
0154 2al502 

0157 f9 

0158 c9 



0159 


e5d5c5 


015c 


OeOb 


015e 


cdOSOO 


0161 


cldiel 


01B4 


c9 


0165 


e5d5c5 


0168 


0e02 


016a 


5f 


016b 


cd0500 


016e 


cldiel 


0171 


c9 


0172 


3e0d 


0174 


cd6501 


0177 


3e0a 


0179 


cd6501 


017c 


c9 



break; 



pchar: 



crlf : 



pnibi 



017d 


e60f 




017f 


feOa 




0181 


d28901 




0184 


c630 




0186 


c38b01 


5 


0189 


c637 


5 

pIO 


018b 


cd6501 


prn 


018e 


c9 





end of dump 

call crlf 

lhld oldsp 

sphl 

stack pointer contains ccp's stack location 

ret ito the ccp 



sub rout ines 

icheck break key (actually any key will do! 

push h! push d! push b! env i ronment saved 

mui c tb rkf 

call bdos 

pop b! pop d! pop hi envi ronment restored 

ret 

5print a characte r 

push h! push d! push b! saued 

tnyi c »typef 

wou e >a 

call bdos 

pop b! pop d! pop h! restored 

ret 



MMl 




aicr 




call 




pchar 




wui 




a»lf 




call 




pchar 




ret 








5 p r i n t 


nibble 


in res a 


ani 




Ofh 


i low 4 bits 


cpi 




10 




Jnc 




pIO 




less 


th 


an or equal to 9 


adi 




'0' 




Jmp 




prn 





Greater or equal to 10 

adi 'a' - 10 

call pchar 
ret 
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phex : 



iprint hex char in re* a 



018f 


f5 


push 


PSW 


0190 


Of 


r re 




0191 


Of 


rrc 




0192 


Of 


rrc 




0193 


Of 


rrc 




0194 


cd7d01 


call 


pnib 


0197 


fl 


POP 


PSW 


0198 


cd7d01 


call 


pnib 


019b 


c9 


ret 





5 print nibble 



019c 0e09 
019e cdOSOO 
Olal c9 



Sprint error message 

d>e addresses message ending with"*" 

mui c»printf iprint buffer function 

call bdos 

ret 



Snb 



01a2 3al302 
01a5 fe80 
01a7 c2b301 



Olaa 


cdceOl 


Olad 


b7 


Olae 


cab301 


Olbl 


37 


01b2 


c9 


01b3 


5f 


01b4 


1600 


OlbG 


3c 


01b7 


321302 


Olba 


218000 


Olbd 


19 


Olbe 


7e 


Olbf 


b7 


OlcO 


c9 



30: 



i*et 


next byte 


Ida 


ibp 


cpi 


BOh 


Jnz 


SO 


read 


another buffer 


call 


disKr 


o ra 


a !ze 


Jz 


SO 5f o 



izero value if read oK 

5for another byte 
end of data* return with carry set for eof 
stc 
ret 

Jread the byte at buff+reS a 

itiou e»a ils byte of buffer index 

mvi d>0 Sdouble precision index to de 

inr a >index=index+l 

sta ibp ibacK to Memory 

pointer is incremented 

saue the current file address 

lxi htbuff 

dad d 

absolute character address is in hi 

mou a m 

byte is in the accumulator 

ora a ireset carry bit 

ret 
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setup: iset up file 

5 open the file for input 



Olcl 


af 


x ra 


a 


izero to accum 


01c2 


327c00 


sta 


f cbc r 


iclear current record 


01c5 


5 

115c00 


lxi 


d.fcb 




01c8 


OeOf 


my i 


c »openf 




Olca 


cdOSOO 


call 


bdos 






» 


255 in 


accum if 


open error 


Olcd 


c9 


ret 








1 

disKr: 


iread > 


disK file 


record 


Olce 


e5d5c5 


push h 


! push d! 


push b 


Oldl 


115c00 


lxi 


d.fcb 




01d4 


0el4 


mvi 


c t readf 




OldG 


cdOSOO 


call 


bdos 




01d9 


cldlel 


pop b ! 


pop d! pop h 


Oldc 


c9 


ret 







i fixed message area 

Oldd 46494c0sianon: db 'file dump version 2.0*' 

01 f 3 OdOa4eOopnms$: db cr»lf»'no input file present on disk$ 

5 variable area 

0213 ibp: ds 2 jinput buffer pointer 

0215 oldsp: ds 2 ientry sp value from ccp 

i 

i stack area 

0217 ds 64 ireserve 32 level stack 

s t k t o p : 

? 

0257 end 
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4.3 A Sample Random Access Program 

This example is an extensive but complete example of random access operation. 
The following program reads or writes random records upon command from the 
terminal. When the program has been created, assembled, and placed into a file 
labeled RANDOM.COM, the CCP level command 

A> RANDOM X.DAT 

can start the test program. In this case, the RANDOM program looks for a file 
X.DAT and, if it finds it, prompts the console for input. If X.DAT is not found, 
RANDOM creates the file before displaying the prompt. Each prompt takes the 
form: 

next command? 

and is followed by operator input, terminated by a carriage return. The input com- 
mands take the form: 

nW nR nF Q 

where n is an integer value in the range to 262143, and W, R, F, and Q are simple 
command characters corresponding to random write, W, random read, R, random 
write with zero fill, F, and quit processing, Q. If you enter a W or F command, the 
RANDOM program issues the prompt: 

type dat a ; 

You then respond by typing up to 127 characters, followed by a carriage return. 
RANDOM then writes the character string into the X.DAT file at record n. If you 
enter an F command, the RANDOM program fills previously unallocated data blocks 
with zeros before writing record n. If you enter the R command, RANDOM reads 
record number n and displays the string value at the console. If you enter the Q 
command, the X.DAT file is closed, and the program returns to the console com- 
mand processor. In the interest of brevity, the only error message is: 

errori try aiain 
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The program begins with an initialization section where the input file is opened or 
created, followed by a continuous loop at the label ready where the individual com- 
mands are interpreted. The program uses the default file control block at 005 CH and 
the default buffer at 0080H in all disk operations. The utility subroutines that follow 
contain the principal input line processor, called readc. This particular program shows 
the elements of random access processing and can be used as the basis for further 
program development. 



0100 

0000 
0005 

0001 
0002 
0009 
000A 
000C 
000F 
0010 
001G 
0021 
0022 
0028 
0098 

005C 
007D 
007F 
0080 

000D 
000A 



i* * 

!* saniple random access program for cp/m 3 

;* 

o rg 



* 
* 

lOOh ibase of tpa 



reboot 
bdos 



equ 
equ 



equ 
equ 



coninp 
conout 
pstring eiu 
rstring e<=iu 
ue rs ion eiu 
openf equ 
closef 
makef 
read r 
writer 
wrt rzf 
parsef 



fcb 

ran rec 

ranouf 

buff 

5 

c r 

If 



equ 
equ 
equ 
equ 
equ 
equ 



equ 
equ 
equ 
equ 

equ 
equ 



OOOOh 
0005h 

1 

2 

9 

10 

12 

15 

16 

22 

33 

34 

40 

152 

005ch 
fcb+33 
fcb+35 
0080h 

Odh 
Oah 



system reboot 
bdos entry point 

console input function 
console output function 
print string' until '*' 
read console buffer 
return yersion number 
file open function 
close function 
wake file function 
read random 
write random 
write random zero fill 
parse function 

default file control block 
random record position 
hish order (overflow) byte 
buffer address 

carriage return 
line feed 
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5* * 

5* load SP> set-up file for random access # 

;# # 

0100 313703 lxi sp»stack 

5 

5 Me rsion 3. 1? 
0103 0E0C mvi c tuersion 

0105 CD0500 call bdos 

0108 FE20 cpi 31h iuersion 3,1 or better? 

010A D21B01 Jnc versok 

5 bad version* message and do bacK 
010D 118102 lxi d»badver 

0110 CD3102 call print 

0113 C30000 Jmp reboot 

5 
uersok : 

i correct version for random access 
0116 OEOF mvi c»openf iopen default fob 

0118 3A5D00 rdname: 
01 IB FE20 
01 ID C22C01 
0120 11E002 
0123 CD3102 
012G CD2002 
0128 C31801 

012C 115C00 opfile: 
012F CD0500 

0132 3C inr a 5err 255 becomes zero 

0133 C24B01 



013G 0E1B 

0138 115C00 

013B CD0500 

013E 3C inr a Serr 255 becomes zero 

013F C24B01 

! 

5 cannot create file* directory full 
0142 11A002 lxi d»nospace 

0145 CD3102 call print 

0148 C30000 Jmp reboot iback to ccp 



mui 


c >openf 


Ida 


fcb + 1 


cpi 


' ' 


Jnz 


opf i le 


lxi 


d >entmsd 


call 


print 


call 


parse 


Jmp 


rdname 


lxi 


d»fcb 


call 


bdos 


in r 


a 


Jnz 


ready 


cannot 


open file 


mui 


c >makef 


lxi 


d »f cb 


call 


bdos 


in r 


a 


Jnz 


ready 
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;* * 

;* loop back to "ready" after each command * 
»# * 

5 

ready: 

! file is ready for processing 

5 

014B CD3C02 call readcom »read next command 

014E 227D00 shld ranrec istore input record* 

0151 217F00 lxi h»ranouf 

0154 71 mom m»c iset ranrec hitfh byte 

0155 FE51 cpi '0' 5quit? 
0157 C2B901 Jnz notq 

! 

5 quit processing* close file 

015A 0E10 mvi c »closef 

015C 115C00 lxi d*fcb 

015F CD0500 call bdos 

01B2 3C inr a ierr 255 becomes 

01G3 CAFF01 Jz error ierror message* retry 

01GB C30000 Jmp reboot 5back to ccp 

5 

;# # 

!* end of quit command* process write * 

i* * 

notq : 

! not the quit command* random write? 

01G9 FE57 cpi 'W 

016B C29C01 Jnz notw 

5 

5 this is a random write* fill buffer until cr 

01GE 11B302 lxi d .datms* 

0171 CD3102 call print idata prompt 

0174 0E7F mui c*127 iup to 127 characters 

017G 218000 lxi h»buff destination 

rloop: 5 read next character to buff 

0179 C5 push b isaue counter 
017A E5 push h inext destination 
017B CD0802 call Setchr jcharacter to a 
017E El pop h Jrestore counter 
017F CI pop b irestore next to fill 

0180 FEOD cpi cr iend of line? 
0182 CA8B01 Jz erloop 
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! not end* store character 

0185 77 mou m*a 

0186 23 inx h Jnext to fill 

0187 0D dor c icounter does down 

0188 C27901 Jnz rloop iend of buffer? 

e rloop: 

! end of read loop* store 00 

018B 3600 mui m>0 

5 

5 write the record to selected record number 

018D 0E22 mui c >writer 

018F 115C00 lxi d»fcb 

0192 CD0500 call bdos 

0185 67 ora a Jerror code zero? 

019B C2FF01 Jnz error JmessaSe if not 

0139 C34B01 JMP ready !for another record 



5# # 

!* end of write command* process write random zero fill # 

5* # 

;*#*###*#*#♦######*##*#**###**######*###*#***#*#*#*####*# 

n o t w : 

! not the suit command* random write zero fill? 

019C FE46 cpi 'F' 

019E C2CF01 Jnz notf 

! 

i this is a random write* fill buffer until cr 

01A1 11B302 lxi d.datms* 

01A4 CD3102 call print idata prompt 

01A7 0E7F mui c»127 iup to 127 characters 

01A9 218000 lxi h.buff idestination 

rloopl: Jread next character to buff 

01AC C5 push b isaue counter 

01AD E5 push h inext destination 

01AE CD0802 call Setchr 5character to a 

01B1 El pop h Jrestore counter 

01B2 CI pop b irestore next to fill 

01B3 FEOD cpi cr 5end of line? 

01B5 CABE01 Jz erloopl 

5 not end* store character 

01B8 77 rnov m»a 

01B9 23 inx h .next to fill 

01BA OD dor c icounter does down 

01BB C2AC01 Jnz rloopl !end of buffer? 
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e r 1 o o p 1 : 

i end of read 1oop> store 00 
01BE 3600 mui M»0 

5 

» write the record to selected record number 
01CO 0E28 
01C2 115C00 
01C5 CD0500 

01C8 B7 ora a 5error code zero? 

01C9 C2FF01 Jnz error »messa<*e if not 

01CC C34B01 Jmp ready ifor another record 

5 

;# * 

i* end of write commands* process read * 

5# * 

notf : 

5 not a write command* read record? 

01CF FE52 cpi 'R' 

01D1 C2FF01 Jnz error 5sKip if not 



mui 


c >wrt rzf 


lxi 


d»fcb 


call 


bdos 


o ra 


a 


Jnz 


error 


Jmp 


ready 



read random record 



wIoop: 



01D4 0E21 

01D6 115C00 

01D9 CD0500 

01DC B7 

01DD C2FF01 



01E0 CD1502 
01E3 0E80 
01E5 218000 

01EB 7E 
01E9 23 
01EA EB7F 
01EC CA4B01 
01EF C5 
01F0 E5 
01F1 FE20 
01F3 D40E02 
01FB El 
01F7 CI 
01F8 OD 
01F9 C2E801 
01FC C34B01 
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mui 


c » readr 






lxi 


d.fcb 






call 


bdos 






o ra 


a 


ireturn code 00? 




Jnz 


e rro r 






read 


was success 


f ul t write to consol e 




call 


crlf 


inew line 




mui 


c.128 


imax 128 characters 




lxi 


h.buff 


5next to Set 




mou 


a >m 


inext character 




inx 


h 


!next to Set 




ani 


7fh 


imask parity 




Jz 


ready 


ifor another command if 


00 


push 


b 


!save counter 




push 


h 


isaue next to Set 




cpi 


' ' 


53raphic? 




cnc 


putch r 


!skip output if not 




POP 


h 






POP 


b 






dc r 


c 


!count=count-l 




Jnz 


wIoop 






Jmp 


ready 
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;##*####***#*♦****#**##**#**##**##**#*#*####****##*# 
;* * 

!* end of read command > all errors end-up here # 

;# * 

! 

error: 
01FF 11BF02 lxi d»errms* 

0202 CD3102 call print 

0205 C34B01 JfiiP ready 

5 

;* # 

5* utility subroutines for console i/o * 

i* # 

Setch r : 

iread next console character to a 
0208 0EO1 mui c »coninp 

020A CD0500 call bdos 

020D C9 ret 

! 
putch rj 

•write character from a to console 
020E 0EO2 mui c >conout 

0210 5F mou eta 5character to send 

0211 CD0500 call bdos !send character 

0214 C9 ret 

5 
crlf : 

Jsend carriage return line feed 

0215 3E0D mui a»cr 5carriase return 
0217 CD0E02 call putchr 

021A 3E0A mui a»lf Uine feed 

021C CD0E02 call putchr 

021F C9 ret 



Jread and parse filespec 

0220 11F102 lxi d »conbuf 

0223 OEOA mui c irstrin* 

0225 CD0500 call bdos 

0228 111303 lxi d »pfncb 

022B 0E98 mui c >parsef 

022D CD0500 call bdos 

0230 C9 ret 
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print: 

Sprint the buffer addressed by de until * 

0231 D5 push d 

0232 CD1502 call crlf 

0235 Dl pop d 5new line 

023G 0E09 wui c »pst rin* 

0238 CD0500 call bdos jprint the string 

023B C9 ret 

i 

readcom: 

5read the next command line to the conbuf 

023C 11D102 lxi d .prompt 

023F CD3102 call print icommand? 

0242 OEOA mvi c trst rinS 

0244 11F102 lxi d»conbuf 

0247 CD0500 call bdos 5 read command line 

i command line is present* scan it 

024A 0E00 mvi c »0 istart with 00 

024C 210000 lxi h ,0 5 0000 

024F 11F302 lxi d tconl in 5 command line 

0252 1A readc: ldax d inext command character 

0253 13 inx d 5to next command position 

0254 B7 ora a Jcannot be end of command 

0255 CB rz 

5 not ze ro * nume ric? 

0256 D630 sui '0' 

0258 FEOA cpi 10 icarry if numeric 

025A D27902 Jnc endrd 
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025D F5 
025E 79 
025F 29 
02B0 8F 

0261 F5 

0262 E5 

0263 29 

0264 8F 

0265 29 

0266 8F 

0267 CI 

0268 09 

0269 CI 
026A 88 
026B CI 
026C 48 
026D 0600 
02BF 09 

0270 CE00 

0272 4F 

0273 D25202 
0276 C33C02 



add-in 


next 


diait 


push 


PSW 






MOU 


a »c 




iualue in ahl 


dad 


h 






adc 


a 




5*2 


push 


a 




isaue ualue * 2 


push 


h 






dad 


h 




5*4 


adc 


a 






dad 


h 




5*8 


adc 


a 






POP 


b 




5*2 + #8 = #10 


dad 


b 






POP 


b 






adc 


b 






POP 


b 




5+diSit 


MOM 


c *b 






mui 


b»0 






dad 


b 






aci 









mou 


c ta 






Jnc 


read 


c 




JMP 


read 


com 





end rd : 



5 end of read* restore ualue in a 

0279 C630 adi '0' icommand 

027B FE61 cpi 'a' itranslate case? 

027D D8 re 

5 lower case* mask lower case bits 
027E E65F ani 101*1 111b 

0280 C9 ret ireturn with ualue in chl 

5 

i #####*###*##*##**##♦#***####***##*#*###**###*#*##** 

;# * 

5* strin* data area for console messages * 

5* # 

;#***##*♦##*#**#*#######*#*#**###*#*****#####**##*#* 

badue r: 

0281 736F727279 db 'sorry* you need cp/m uersion 3$' 

nospace : 
02A0 6E6F20B469 db 'no directory space*' 

datmss: 
02B3 7479706520 db 'type data: *' 

errwss: 
02BF B572726F72 db 'error* try asain.*' 

prompt : 
02D1 BE65787420 db 'next command? *' 

en tins 3: 
02E0 B56E746572 db 'enter filename: $' 
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i* * 

»* fixed and variable data area * 

!* * 

02F1 21 conbuf: db conlen ilensth of console buffer 

02F2 consiz: ds 1 iresultind size after read 

02F3 oonlin: ds 32 SlenSth 32 buffer 

0021 = conlen e<=iu *-consiz 

! 

pf neb : 

0313 F302 dw conlin 

0315 5C00 dw feb 

! 

0317 ds 32 516 level stack 

stack: 

0337 end 

You could make the following major improvements to this program to enhance its 
operation. With some work, this program could evolve into a simple data base 
management system. You could, for example, assume a standard record size of 128 
bytes, consisting of arbitrary fields within the record. You could develop a program 
called GETKEY that first reads a sequential file and extracts a specific field defined 
by the operator. For example, the command 

GETKEY NAMES.DAT LASTNAME 10 20 

would cause GETKEY to read the data base file NAMES.DAT and extract the 
"LASTNAME" field from each record, starting at position 10 and ending at charac- 
ter 20. GETKEY builds a table in memory consisting of each particular LASTNAME 
field, along with its 16-bit record number location within the file. The GETKEY 
program then sorts this list and writes a new file, called LASTNAME.KEY. This list, 
sometimes called an inverted index, is an alphabetical list of LASTNAME fields with 
their corresponding record numbers. 

You could rename the program shown above to QUERY, and modify it so that it 
reads a sorted key file into memory. The command line might appear as 

QUERY NAMES.DAT LASTNAME.KEY 
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Instead of reading a number, the QUERY program reads an alphanumeric string 
which is a particular key to find in the NAMES.DAT data base. Because the LAST- 
NAME. KEY list is sorted, you can find a particular entry quickly by performing a 
binary search, similar to looking up a name in the telephone directory. Start at both 
ends of the list and examine the entry halfway in between and, if not matched, split 
either the upper half or the lower half for the next search. You will quickly reach the 
item you are looking for, in log2(n) steps, where you will find the corresponding 
record number. Fetch and display this record at the console as the program illustrates. 

At this point, you are just getting started. With a little more work, you can allow 
a fixed grouping size, which differs from the 128-byte record shown above. You can 
accomplish this by keeping track of the record number as well as the byte offset 
within the record. Knowing the group size, you can randomly access the record 
containing the proper group, offset to the beginning of the group within the record, 
and read sequentially until the group size has been exhausted. 

Finally, you can improve QUERY considerably by allowing Boolean expressions 
that compute the set of records that satisfy several relationships, such as a LAST- 
NAME between HARDY and LAUREL and an AGE less than 45. Display all the 
records that fit this description. Finally, if your lists are getting too big to fit into 
memory, randomly access your key files from the disk as well. 



4.4 Construction of an RSX Program 

This section describes the standard prefix of a Resident System Extension (RSX) 
and illustrates the construction of an RSX with an example. (See Section 1.6.4 for a 
discussion of how RSXs operate under CP/M 3.) RSX programs are usually written 
in assembler, but you can use other languages if the interface between the language 
and the calling conventions of the BDOS are set up properly. 
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4.4.1 The RSX Prefix 

The first 27 bytes of an RSX program contain a standard data structure called the 
RSX prefix. The RSX prefix has the following format: 



serial: 
















db 


OtOtO 


»0 


*0t0 






start : 














'r 


Jmp 


f test 






5 start of pro Sram 




next : 














H 


db 


0c3h 






5 Jump inst ruction 


to 


A 


dw 









5 next modul e in 1 


ine 


p rev : 














c 


dw 









5 previous modul e^e 


Oblf"' 


remove : 












}\' -' 


t 


db 


Offh 






» remove flasf 


V' i> t ■ 


nonbank : 














f 


db 









5 nonbank f 1 a sf 




name : 














to 


db 


'12345G78' 


5 any 8-character 


name 


loader: 














iff 


db 
db 



0»0 






5 loader f lad 
5 reserved area 





The only fields of the RSX prefix that you must initialize are the remove: flag, the 
nonbank: flag, and the name: of the RSX. 

For compatibility with previous releases of CP/M, the serial: field of the prefix is 
set to the serial number of the operating system by the LOADER module when the 
RSX is loaded into memory. Thus, the address in location 6 locates the byte follow- 
ing the serial number of the operating system with or without RSXs in memory. 

The start: field contains a jump instruction to the beginning of the RSX code 
where the RSX tests to see if this BDOS function call is to be intercepted or passed 
on to the next module in line. 

The next: field contains a jump instruction to the next module in the chain or the 
LOADER module if the RSX is the oldest one in memory. The RSX program must 
make its own BDOS function calls by calling the next: entry point. 



DIGITAL RESEARCH 7 



4-21 



4.4 Construction of an RSX Program CP/M 3 Programmer's Guide 

The prev: field contains the address of the preceding RSX in memory or location fr 
if the RSX is the first RSX in the chain. 

The remove: field controls whether the RSX is removed from memory by the next 
call to the LOADER module via BDOS function 59. If the remove: flag is OFFH, the 
LOADER removes the RSX from memory. Note that the CCP always calls the 
LOADER module during a warm start operation. An RSX that remains in memory 
past warm start because its remove: flag is zero, must set the flag at its termination 
to ensure its removal from memory at the following warm start. 

The nonbank: field controls when the RSX is loaded. If the field is OFFH, the 
LOADER only loads the module into memory on nonbanked CP/M 3 systems. 
Otherwise, the RSX is loaded into memory under both banked and nonbanked ver- 
sions of CP/M 3. 

The loader: flag identifies the LOADER RSX. When the LOADER module loads 
an RSX into memory, it sets this prefix flag of the loaded RSX to zero. However, the 
loader: flag in the LOADER'S prefix contains OFFH. Thus, this flag identifies the last 
RSX in the chain, which is always the LOADER. 

4.4.2 Example of RSX Use 

These two sample programs illustrate the use of an RSX program. The first 
program, CALLVERS, prints a message to the console and then makes a BDOS 
Function 12 call to obtain the CP/M 3 version number. CALLVERS repeats this 
sequence five times before terminating. The second program, ECHO VERS, is an RSX 
that intercepts the BDOS Function 12 call made by CALLVERS, prints a second 
message, and returns the version 003 1H to CALLVERS. Although this example is 
simple, it illustrates BDOS function interception, stack swapping, and BDOS function 
calls within an RSX. 
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0005 


= 


0009 


= 


oooc 


= 


000D 


= 


000A 


= 


0100 




0100 


1605 


0102 


D5 


0103 


0E09 


0105 


111E01 


0108 


CD0500 


010B 


0E0C 


010D 


CD0500 


0110 


7D 


0111 


323401 


0114 


Dl 


0115 


15 


0116 


C20201 


0119 


0E00 


01 IB 


C30500 



! CALLVERS program 
bdos equ 5 

prtstr equ 9 

vers equ 12 

or equ Odh 

If equ Oah 



loop: 



o rs 


lOOh 


mvi 


d»5 


push 


d 


mvi 


c .prtst r 


lxi 


d >cal 1*msS 


call 


bdos 


mvi 


c »ve rs 


call 


bdos 


trtOV 


a.l 


sta 


curve rs 


POP 


d 


do r 


d 


Jnz 


loop 


mvi 


c .0 


Jmp 


bdos 



cal l$msd: 
011E 0D0A2A2A2A db 

0134 00 curvers db 

0135 end 



entry point for BDOS 
print string function 
Set version function 
carriage return 
line feed 



i Perforin 5 times 
i save counter 

i print call message 



i try to Set version * 
5 CALLVERS will intercept 



i decrement counter 



cr.lf »'**** CALIPERS **** * 




5 ECHOVERS RSX 



0009 = 


pst rins 


equ 


9 


000D = 


c r 


equ 


Odh 


OOOA = 


If 


equ 


Oah 



! strinS print function 



RSX PREFIX STRUCTURE 



0000 000000000( 


) 


db 


.0 .0 





.0,0 


room for serial number 


0006 C31B00 




Jmp 


ftest 






besin of program 


0009 C3 


next : 


db 


0c3H 






Jump 


OOOA 0000 




dw 









next module in line 


OOOC 0000 


prev : 


dw 









previous module 


OOOE FF 


remov : 


db 


Offh 






remove fla? set 


OOOF 00 


nonbnk : 


db 











0010 4543484F56 


db 


'ECHOVERS' 




0018 000000 




db 


0.0.0 
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ftest: 



i is this function 12? 



001B 


79 


MOV 


a >c 




001C 


FE0C 


opi 


12 




001E 


CA2400 


Jz 


beSin 


! yes - intercept 


0021 


C30900 


JfrtP 


next 


5 some other function 




bedin: 






0024 


210000 


lxi 


h>0 




0027 


39 


dad 


SP 


i save stack 


0028 


225400 


shld 


ret*stack 




002B 


317G00 


lxi 


sp »loc$stacK 




002E 


0E09 


mui 


c »P5t rinsl 




0030 


113E00 


lxi 


d >test$MsS 


! print message 


0033 


CD0900 


call 


next 


i call BDOS 


0036 


2A5400 


lhld 


ret$stacK 


i restore user stack 


0039 


F9 


sphl 






003A 


213100 


lxi 


h»0031h 


i return version nuntb 


003D 


C9 


ret 







testtmsS: 
003E 0D0A2A2A2A db 

ret*stack: 
0054 0000 dw 

0056 ds 

loc$stack : 
0076 end 



cr>lf »'***# ECHOVERS **#*$' 




32 



i 16 level stack 
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You can prepare the above programs for execution as follows: 

1. Assemble the CALLVERS program using MAC as follows: 
MAC CALIPERS 

2. Generate a COM file for CALLVERS with HEXCOM: 
HEXCOM CALLVERS 

3. Assemble the RSX program ECHOVERS using RMAC: 
RMAC ECHOVERS 

4. Generate a PRL file using the LINK command: 
LINK ECHOVERS COP] 

5. Rename the PRL file to an RSX file: 
RENAME ECHOVERS ♦RSX=ECHOVERS. PRL 

6. Generate a COM file with an attached RSX using the GENCOM command: 
GENCOM CALLVERS ECHOVERS 

7. Run the CALLVERS.COM module: 
CALLVERS 

The message 

**** CALLVERS **#* 

followed by the message 
**** ECHOVERS **#* 

appears on the screen five times if the RSX program works. 

End of Section 4 
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System Control Block 



The System Control Block (SCB) is a CP/M 3 data structure located in the BDOS. 
CP/M 3 uses this region primarily for communication between the BDOS and the 
BIOS. However, it is also available for communication between application pro- 
grams, RSXs, and the BDOS. Note that programs that access the System Control 
Block are not version independent. They can run only on CP/M 3. 

The following list describes the fields of the SCB that are available for access by 
application programs and RSXs. The location of each field is described as the offset 
from the start address of the SCB (see BDOS Function 49). The RW/RO column 
indicates if the SCB field is Read- Write or Read-Only. 



Table A-l. SCB Fields and Definitions 



Offset 


RW/RO 


Definition 


00 — 04 


RO 


Reserved for system use. 


05 


RO 


BDOS Version Number. 


06 — 09 


RW 


Reserved for user use. Use these four bytes for your 
own flags or data. 


0A — OF 


RO 


Reserved for system use. 


10 — 11 


RW 


Program Error Return Code. This 2-byte field can be 
used by a program to pass an error code or value to a 
chained program. CP/M 3's conditional command facil- 
ity also uses this field to determine if a program exe- 
cutes successfully. The BDOS Function 108 (Get/Set 
Program Return Code) is used to get/set this value. 


12 — 19 


RO 


Reserved for system use. 
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Table A-l. (continued) 



Offset 



RW/RO 



Definition 



1A 



IB 



1C 



ID — 21 
22 — 2B 



RW Console Width. This byte contains the number of col- 

umns, characters per line, on your console relative to 
zero. Most systems default this value to 79. You can 
set this default value by using the GENCPM or the 
DEVICE utility. The console width value is used by the 
banked version of CP/M 3 in BDOS function 10, 
CP/M 3's console editing input function. Note that typ- 
ing a character into the last position of the screen, as 
specified by the Console Width field, must not cause 
the terminal to advance to the next line. 

RO Console Column Position. This byte contains the cur- 

rent console column position. 

RW Console Page Length. This byte contains the page length, 

lines per page, of your console. Most systems default 
this value to 24 lines per page. This default value may 
be changed by using the GENCPM or the DEVICE util- 
ity (see the CP/M Plus (CP/M Version 3) Operating 
System User's Guide). 

RO Reserved for system use. 

RW Redirection flags for each of the five logical character 

devices. If your system's BIOS supports assignment of 
logical devices to physical devices, you can direct each 
of the five logical character devices to any combination 
of up to 12 physical devices. The 16-bit word for each 
device represents the following: 

Each bit represents a physical device where bit 15 cor- 
responds to device zero and bit 4 corresponds to device 
11. Bits zero through 3 are reserved for system use. 

You can redirect the input and output logical devices 
with the DEVICE command (see CP/M Plus (CP/M 
Version 3) Operating System User's Guide). 
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Table A-l. (continued) 



Offset 


RW/RO 


Definition 


22- 


-23 


RW 


CONIN Redirection Flag. 


24- 


-25 


RW 


CONOUT Redirection Flag. 


26- 


-27 


RW 


AUXIN Redirection Flag. 


28- 


-29 


RW 


AUXOUT Redirection Flag. 


2A- 


-2B 


RW 


LSTOUT Redirection Flag. 


2C 




RW 


Page Mode. If this byte is set to zero, some CP/M 3 
utilities and CCP built-in commands display one page 
of data at a time; you display the next page by pressing 
any key. If this byte is not set to zero, the system dis- 
plays data on the screen without stopping. To stop and 
start the display, you can press CTRL-S and CTRL-Q, 
respectively. 


2D 




RO 


Reserved for system use. 


2E 




RW 


Determines if CTRL-H is interpreted as a rub/del char- 
acter. If this byte is set to 0, then CTRL-H is a back- 
space character (moves back and deletes). If this byte is 
set to OFFH, then CTRL-H is a rub/del character, echoes 
the deleted character. 


2F 




RW 


Determines if rub/del is interpreted as CTRL-H charac- 
ter. If this byte is set to 0, then rub/del echoes the deleted 
character. If this byte is set to OFF, then rub/del is inter- 
preted as a CTRL-H character (moves back and deletes). 


30- 


-32 


RO 


Reserved for system use. 


33- 


-34 


RW 


Console Mode. This is a 16-bit system parameter that 
determines the action of certain BDOS Console I/O 
functions. (See Section 2.2.1 and BDOS Function 109, 
Get/Set Console Mode, for a thorough explanation of 
Console Mode.) 
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Table A-l. (continued) 



Offset 


RW/RO 


Definition 


35 — 36 


RO 


Reserved for system use. 


37 


RW 


Output delimiter character. The default output delim- 
iter character is $, but you can change this value by 
using the BDOS Function 110, Get/Set Output Delimiter. 


38 


RW 


List Output Flag. If this byte is set to 0, console output 
is not echoed to the list device. If this byte is set to 1 
console output is echoed to the list device. 


39 — 3B 


RO 


Reserved for system use. 


3C — 3D 


RO 


Current DMA Address. This address can be set by BDOS 
Function 26 (Set DMA Address). .The CCP initializes 
this value to 0080H. BDOS Function 13, Reset Disk 
System, also sets the DMA address to 0080H. 


3E 


RO 


Current Disk. This byte contains the currently selected 
default disk number. This Value ranges from 0-15 cor- 
responding to drives A-P, respectively. BDOS Function 
25, Return Current Disk, can be used to determine the 
current disk value. 


3F — 43 


RO 


Reserved for system use. 


44 


RO 


Current User Number. This byte contains the current 
user number. This value ranges from 0-15. BDOS Func- 
tion 32, Set/Get User Code, can change or interrogate 
the currently active user number. 


45 — 49 


RO 


Reserved for system use. 


4A 


RW 


BDOS Multi-Sector Count. This field is set by BDOS 
Function 44, Set Multi-Sector Count. 
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Table A-l. (continued) 



Offset 



RW/RO 



Definition 



4B 



RW 



4C — 4F 



RW 



50 



RW 



51 



52 — 56 



RO 



RO 



BDOS Error Mode. This field is set by BDOS Function 
45, Set BDOS Error Mode. 

If this byte is set to OFFH, the system returns to the 
current program without displaying any error messages. 
If it is set to OFEH, the system displays error messages 
before returning to the current program. Otherwise, the 
system terminates the program and displays error mes- 
sages. See description of BDOS Function 45, Set BDOS 
Error Mode, for discussion of the different error modes. 

Drive Search Chain. The first byte contains the drive 
number of the first drive in the chain, the second byte 
contains the drive number of the second drive in the 
chain, and so on, for up to four bytes. If less than four 
drives are to be searched, the next byte is set to OFFH 
to signal the end of the search chain. The drive values 
range from 0-16, where corresponds to the default 
drive, while 1-16 corresponds to drives A-P, respec- 
tively. The drive search chain can be displayed or set 
by using the SETDEF utility (see CP/M Plus (Version 3) 
Operating System User's Guide). 

Temporary File Drive. This byte contains the drive 
number of the temporary file drive. The drive number 
ranges from 0-16, where corresponds to the default 
drive, while 1-16 corresponds to drives A-P, respectively. 

Error drive. This byte contains the drive number of the 
selected drive when the last physical or extended error 
occurred. 

Reserved for system use. 
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Table A-l. (continued) 



Offset 


RW/RO 


Definition 


57 


RO 


BDOS Flags. Bit 7 applies to banked systems only. If 
bit 7 is set, then the system displays expanded error 
messages. The second error line displays the function 
number and FCB information. (See Section 2.3.13). 

Bit 6 applies only to nonbanked systems. If bit 6 is set, 
it indicates that GENCPM has specified single alloca- 
tion vectors for the system. Otherwise, double alloca- 
tion vectors have been defined for the system. Function 
98, Free Blocks, returns temporarily allocated blocks to 
free space only if bit 6 is reset. 


58 —59 


RW 


Date in days in binary since 1 Jan 78. 


5A 


RW 


Hour in BCD (2-digit Binary Coded Decimal). 


5B 


RW 


Minutes in BCD. 


5C 


RW 


Seconds in BCD. 


5D — 5E 


RO 


Common Memory Base Address. This value is zero for 
nonbanked systems and nonzero for banked systems. 


5F — 63 


RO 


Reserved for system use. 



End of Appendix A 



A-6 



DIGITAL RESEARCH 7 



Appendix B 
PRL File Generation 



B.l PRL Format 

A Page Relocatable Program has an origin offset of 100H bytes that is stored on 
disk as a file of type PRL. The format is shown in Table B-l. 



Table B-l. PRL File Format 



Address 



Contents 



0001-0002H Program size 

0004-0005H Minimum buffer requirements (additional memory) 

0006-OOFFH Currently unused, reserved for future allocation 

0100 + Program size = Start of bit map 



The bit map is a string of bits identifying those bytes in the source code that 
require relocation. There is one byte in the bit map for every 8 bytes of source code. 
The most significant bit, bit 7, of the first byte of the bit map indicates whether or 
not the first byte of the source code requires relocation. If the bit is on, it indicates 
that relocation is required. The next bit, bit 6, of the first byte corresponds to the 
second byte of the source code, and so forth. 
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B.2 Generating a PRL 

The preferred technique for generating a PRL file is to use the CP/M LINK-80™, 
which can generate a PRL file from a REL relocatable object file. This technique is 
described in the Programmer's Utilities Guide for The CP/M Family of Operating 
Systems. A sample link command is shown below. 

A>Jin/f duMPCopJ 



End of Appendix B 
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SPR Generation 



System Page Relocatable, SPR, files are similar in format to PRL files except that 
SPR files have an origin offset of 0000H (see Appendix B). SPR Files are provided as 
part of the standard CP/M 3 System: the resident and banked portions of the banked 
BDOS, named RESBDOS3.SPR and BNKBDOS3.SPR, and the nonbanked BDOS, 
named BDOS3.SPR. The customized BIOS must also be generated in SPR format 
before GENCPM can create a CP/M 3 system. The BIOS SPR file is named 
BNKBIOS3.SPR for banked systems and BIOS3.SPR for nonbanked systems. A detailed 
discussion of the generation of BIOS3.SPR or BNKBIOS3.SPR is provided in the 
CP/M Plus (CP/M Version 3) Operating System System Guide. 

The method of generating an SPR is analogous to that of generating a Page Relo- 
catable Program (described in Appendix B) with the following exceptions: 

■ If LINK-80 is used, the output file of type SPR is specified with the [os] or [b] 
option. The [b] option is used when linking BNKBIOS3.SPR. 

■ The code in the SPR is ORGed at 000H rather than 100H. 



End of Appendix C 
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This appendix contains tables of the ASCII symbols, including their binary, deci- 
mal, and hexadecimal conversions. 



Table D-l. ASCII Symbols 



Symbol 


Meaning 


Symbol 


Meaning 


ACK 


acknowledge 


FS 


file separator 


BEL 


bell 


GS 


group separator 


BS 


backspace 


HT 


horizontal tabulation 


CAN 


cancel 


LF 


line-feed 


CR 


carriage return 


NAK 


negative acknowledge 


DC 


device control 


NUL 


null 


DEL 


delete 


RS 


record separator 


DLE 


data link escape 


SI 


shift in 


EM 


end of medium 


SO 


shift out 


ENQ 


enquiry 


SOH 


start of heading 


EOT 


end of transmission 


SP 


space 


ESC 


escape 


STX 


start of text 


ETB 


end of transmission 


SUB 


substitute 


ETX 


end of text 


SYN 


synchronous idle 


FF 


form-feed 


US 


unit separator 






VT 


vertical tabulation 
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Table D-2. ASCII Conversion Table 


Binary 


Decimal 


Hexadecimal 


ASCII 


0000000 


000 


00 


NUL 


0000001 


001 


01 


SOH (CTRL-A) 


0000010 


002 


02 


STX (CTRL-B) 


0000011 


003 


03 


ETX (CTRL-C) 


0000100 


004 


04 


EOT (CTRL-D) 


0000101 


005 


05 


ENQ (CTRL-E) 


0000110 


006 


06 


ACK (CTRL-F) 


0000111 


007 


07 


BEL (CTRL-G) 


0001000 


008 


08 


BS (CTRL-H) 


0001001 


009 


09 


HT (CTRL-I) 


0001010 


010 


0A 


LF (CTRL-J) 


0001011 


011 


0B 


VT (CTRL-K) 


0001100 


012 


OC 


FF (CTRL-L) 


0001101 


013 


0D 


CR (CTRL-M) 


0001110 


014 


0E 


SO (CTRL-N) 


0001111 


015 


OF 


SI (CTRL-O) 


0010000 


016 


10 


DLE (CTRL-P) 


0010001 


017 


11 


DC1 (CTRL-Q) 


0010010 


018 


12 


DC2 (CTRL-R) 


0010011 


019 


13 


DC3 (CTRL-S) 


0010100 


020 


14 


DC4 (CTRL-T) 


0010101 


021 


15 


NAK (CTRL-U) 


0010110 


022 


16 


SYN (CTRL-V) 


0010111 


023 


17 


ETB (CTRL-W) 


0011000 


024 


18 


CAN (CTRL-X) 


0011001 


025 


19 


EM (CTRL-Y) 


0011010 


026 


1A 


SUB (CTRL-Z) 


0011011 


027 


IB 


ESC (CTRL-D 


0011100 


028 


1C 


FS (CTRL-N) 


0011101 


029 


ID 


GS (CTRL-]) 


0011110 


030 


IE 


RS (CTRL-1 


0011111 


031 


IF 


US (CTRL- ) 


0100000 


032 


20 


(SPACE) 


0100001 


033 


21 


» 


0100010 


034 


22 


/ 


0100011 


035 


23 


# 


0100100 


036 


24 


$ 
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Table D-2. (continued) 



Binary 


Decimal 


Hexadecimal 


ASCII 


0100101 


037 


25 


% 


0100110 


038 


26 


& 


0100111 


039 


27 


> 


0101000 


040 


28 


( 


0101001 


041 


29 


) 


0101010 


042 


2A 


* 


0101011 


043 


2B 


+ 


0101100 


044 


2C 


> 


0101101 


045 


2D 


- 


0101110 


046 


2E 


. 


0101111 


047 


2F 


/ 


0110000 


048 


30 





0110001 


049 


31 


1 


0110010 


050 


32 


2 


0110011 


051 


33 


3 


0110100 


052 


34 


4 


0110101 


053 


35 


5 


0110110 


054 


36 


6 


0110111 


055 


37 


7 


0111000 


056 


38 


8 


0111001 


057 


39 


9 


0111010 


058 


3A 


: 


0111011 


059 


3B 


5 


0111100 


060 


3C 


< 


0111101 


061 


3D 


= 


0111110 


062 


3E 


> 


0111111 


063 


3F 


? 


1000000 


064 


40 


@ 


1000001 


065 


41 


A 


1000010 


066 


42 


B 


1000011 


067 


43 


C 


1000100 


068 


44 


D 


1000101 


069 


45 


E 


1000110 


070 


46 


F 


1000111 


071 


47 


G 


1001000 


072 


48 


H 


1001001 


073 


49 


I 

— — — — ^— — — — ^__^__ 
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Table D-2. (continued) 



Binary 


Decimal 


Hexadecimal 


ASCII 


1001010 


074 


4A 


J 


1001011 


075 


4B 


K 


1001100 


076 


4C 


L 


1001101 


077 


4D 


M 


1001110 


078 


4E 


N 


1001111 


079 


4F 


O 


1010000 


080 


50 


P 


1010001 


081 


51 


Q 


1010010 


082 


52 


R 


1010011 


083 


53 


S 


1010100 


084 


54 


T 


1010101 


085 


55 


U 


1010110 


086 


56 


V 


1010111 


087 


57 


w 


1011000 


088 


58 


X 


1011001 


089 


59 


Y 


1011010 


090 


5A 


Z 


1011011 


091 


5B 


[ 


1011100 


092 


5C 


\ 


1011101 


093 


5D 


] 


1011110 


094 


5E 


A 


1011111 


095 


5F 


< 


1100000 


096 


60 


> 


1100001 


097 


61 


a 


1100010 


098 


62 


b 


1100011 


099 


63 


c 


1100100 


100 


64 


d 


1100101 


101 


65 


e 


1100110 


102 


66 


f 



D-4 



DIGITAL RESEARCH 7 



CP/M 3 Programmer's Guide 



D ASCII and HEX Conversions 



Table D-2. (continued) 



Binary 


Decimal 


Hexadecimal 


ASCII 


1100111 


103 


67 


g 


1101000 


104 


68 


h 


1101001 


105 


69 


i 


1101010 


106 


6A 


J 


1101011 


107 


6B 


k 


1101100 


108 


6C 


1 


1101101 


109 


6D 


m 


1101110 


110 


6E 


n 


1101111 


111 


6F 


o 


1110000 


112 


70 


P 


1110001 


113 


71 


q 


1110010 


114 


72 


r 


1110011 


115 


73 


s 


1110100 


116 


74 


t 


1110101 


117 


75 


u 


1110110 


118 


76 


V 


1110111 


119 


77 


w 


1111000 


120 


78 


X 


1111001 


121 


79 


y 


1111010 


122 


7A 


z 


1111011 


123 


7B 


{ 


1111100 


124 


7C 


1 


1111101 


125 


7D 


} 


1111110 


126 


7E 


~ 


1111111 


127 


7F 


DEL 
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Table E-l. BDOS Function Summary 



Function 


Function Name 


Input Parameters 


Returned Values 





System Reset 


none 


none 


1 


Console Input 


none 


A = char 


2 


Console Output 


E = char 


A = 00H 


3 


Auxiliary Input 


none 


A = char 


4 


Auxiliary Output 


E = char 


A = 00H 


5 


List Output 


E = char 


A = 00H 


6 


Direct Console I/O 


E = OFFH/ 


A = char/status/ 






OFEH/ 


none 






OFDH/ 








char 




7 


Auxiliary Input 
Status 


none 


A = 00/OFFH 


8 


Auxiliary Output 
Status 


none 


A = 00/OFFH 


9 


Print String 


DE = .String 


A = 00H 


10 


Read Console Buffer 


DE = .BufferO 


Characters in buffer 


11 


Get Console Status 


none 


A = 00/01 


12 


Return Version Number 


none 


HL = Version (003 1H) 


13 


Reset Disk System 


none 


A = 00H 


14 


Select Disk 


E = Disk 
Number 


A = Err Flag 


15 


Open File 


DE = .FCB 


A = Dir Code 


16 


Close File 


DE = .FCB 


A = Dir Code 


17 


Search for First 


DE = .FCB 


A = Dir Code 


18 


Search for Next 


none 


A = Dir Code 


19 


Delete File 


DE = .FCB 


A = Dir Code 


20 


Read Sequential 


DE = .FCB 


A = Err Code 


21 


Write Sequential 


DE = .FCB 


A = Err Code 


22 


Make File 


DE = .FCB 


A = Dir Code 


23 


Rename File 


DE = .FCB 


A = Dir Code 


24 


Return Login Vector 


none 


HL = Login Vector 


25 


Return Current Disk 


none 


A = Cur Disk# 
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Table E-l. (continued) 



Function 


Function Name 


Input Parameters 


Returned Values 


25 


Return Current Disk 


none 


A = Cur Disk# 


26 


Set DMA Address 


DE = .DMA 


A = 00H 


27 


Get Addr(Alloc) 


none 


HL = .Alloc 


28 


Write Protect Disk 


none 


A = 00H 


29 


Get R/O Vector 


none 


HL = R/O Vector 


30 


Set File Attributes 


DE = .FCB 


A = Dir Code 


31 


Get Addr(DPB) 


none 


HL = .DPB 


32 


Set/Get User Code 


E = OFFH/ 


A = Curr User/ 






user number 


00H 


33 


Read Random 


DE = .FCB 


A = Err Code 


34 


Write Random 


DE = .FCB 


A = Err Code 


35 


Compute File Size 


DE = .FCB 


rO, rl, r2 
A = Err Flag 


36 


Set Random Record 


DE = .FCB 


rO, rl, r2 


37 


Reset Drive 


DE = Drive 
Vector 


A = 00H 


38 


Access Drive 


none 


A = 00H 


39 


Free Drive 


none 


A = 00H 


40 


Write Random with 
Zero Fill 


DE = .FCB 


A = Err Code 


41 


Test and Write Record 


DE = .FCB 


A = OFFH 


42 


Lock Record 


DE = .FCB 


A = 00H 


43 


Unlock Record 


DE = .FCB 


A = 00H 


44 


Set Multi-sector Count 


E = # Sectors 


A = Return Code 


45 


Set BDOS Error Mode 


E = BDOS Err 
Mode 


A = 00H 


46 


Get Disk Free Space 


E = Drive 


Number of Free Sectors 






number 


A = Err Flag 


47 


Chain to Program 


E = Chain Flag 


A = 00H 


48 


Flush Buffers 


E = Purge Flag 


A = Err Flag 


49 


Get/Set System 


DE = .SCB PB 


A = Returned Byte 




Control Block 




HL = Returned Word 


50 


Direct BIOS Calls 


DE = .BIOS PB 


BIOS Return 


59 


Load Overlay 


DE = .FCB 


A = Err Code 


60 


Call Resident System 
Extension 


DE = .RSX PB 


A = Err Code 



Note: . indicates the address of 
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Table E-l. (continued) 




Function 


Function Name 


Input 


Parameters 


Returned Values 


98 


Free Blocks 


none 




A = Err Flag 


99 


Truncate File 


DE = 


.FCB 


A = Dir Code 


100 


Set Directory Label 


DE = 


.FCB 


A = Dir Code 


101 


Return Directory 


E = Drive 


A = Dir label data byte 




Label Data 








102 


Read File Date Stamps 
and Password Mode 


DE = 


.FCB 


A = Dir Code 


103 


Write File XFCB 


DE = 


.FCB 


A = Dir Code 


104 


Set Date and Time 


DE = 


.DAT 


A = 00H 


105 


Get Date and Time 


DE = 


.DAT 


Date and Time 
A = seconds 


106 


Set Default Password 


DE = 


.Password 


A = 00H 


107 


Return Serial Number 


DE = 


.Serial # 
field 


Serial Number 


108 


Get/Set Program 


DE = 


0FFFFH/ 


HL Program Ret Code 




Return Code 


Code 




none 


109 


Get/Set Console Mode 


DE = 
Mode 


0FFFFH/ 


HL = Console Mode 
none 


110 


Get/Set Output 


DE = 


0FFFFH/ 


A = Output Delimiter 




Delimiter 


E = 


Delimiter 


none 


111 


Print Block 


DE = 


.CCB 


A = 00H 


112 


List Block 


DE = 


.CCB 


A = 00H 


152 


Parse Filename 


DE = 


.PFCB 


See definition 



Note: . indicates the address of 
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absolute module, 3-73 
Access date and time stamp, 3-21 
Access Drive MP/M, 3-57 
access stamp types, 2-24 
address maximum, 1-5 
allocation vector, 3-41, 3-75 
allocation file space, 1-13 
ambiguous file reference, 1-13, 2-16, 

3-24 
Archive Attribute, 2-17 
ASM, 2-11 

assign password, 2-17, 2-20 
associated command files, 1-18 
asterisk, 1-13, 2-11 
attach RSX, 1-9 
Attributes 

bits, 2-16 

Set File, 2-22 
automatic submit option, 1-19, 1-20 
Auxiliary Input, 2-2, 3-9 

Output, 3-10 
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backspace, 3-2 
BAK, 2-11 
Bank 0, 1-2, 1-3 
Bank 1, 1-3 
bank switching, 1-2 
bank-switched memory, 1-1, 1-2 
BAS, 2-11 

base extent, 3-48, 3-50 
basic console I/O, 2-3 
Basic Disk Operating System BDOS, 
1-6 



Basic Input/Output System BDOS, 1-6 
basic record size, 2-7 
BDOS, 1-6, 1-7, 1-8, 1-11, 1-13 
BDOS Call Resident System Extension, 
1-24 

Calling Conventions, 2-1 

Chain to Program, 1-23 

Directory Codes, 2-32 

entry point, 2-35 

Error Codes, 2-31 

Error Flag, 2-33 

Error Mode, 2-33 

extended error codes, 2-34 

file system, 2-7, 2-11 

function entry parameters, 1-8 

functional, 2-4 

functions, 1-24 

physical error codes, 2-33 

Program Chain, 2-18 

Read Console Buffer, 1-16 

set directory label, 1-25 

Set User, 2-18 

size, 1-11 

System Reset, 2-1 

warm start entry point, 1-15, 1-23, 
2-35 
BDOS base, 1-8, 1-9, 1-11, 1-15 
BIOS, 1-6, 1-7, 1-11, 1-15, 2-29 
Cold Boot entry point, 1-14 
DEVTBL, 2-2 
entry points, 1-23 
Parameter Block, 3-69 
BDOS function, 1-8, 1-23, 2-29 
BDOS Function calls: 

ACCESS DRIVE, 3-57 

AUXILIARY INPUT, 3-4 

AUXILIARY INPUT STATUS, 3-9 

AUXILIARY OUTPUT, 3-5 
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AUXILIARY OUTPUT STATUS, 

3-10 
CALL RESIDENT SYSTEM 

EXTENSION, 3-74 
CHAIN TO PROGRAM, 3-67 
CLOSE FILE, 3-22 
COMPUTE FILE SIZE, 3-53 
CONSOLE INPUT, 3-2 
CONSOLE OUTPUT, 3-3 
DELETE FILE, 3-27 
DIRECT BIOS CALLS, 3-72 
DIRECT CONSOLE I/O, 3-7 
FLUSH BUFFERS, 3-68 
FREE BLOCKS, 3-75 
FREE DRIVE, 3-58 
GET ADDR(ALLOC), 3-41 
GET ADDR(DPB PARMS), 3-41 
GET/SET CONSOLE MODE, 3-91 
GET CONSOLE STATUS, 3-16 
GET DATE AND TIME, 3-86 
GET DISK FREE SPACE, 3-65 
GET READ-ONLY VECTOR, 3-43 
GET/SET PROGRAM RETURN 

CODE, 3-89 
GET/SET OUTPUT DELIMITER, 

3-93 
GET/SET SYSTEM CONTROL 

BLOCK, 3-69 
LIST BLOCK, 3-95 
LOCK RECORD, 3-61 
LIST OUTPUT, 3-6 
LOAD OVERLAY, 3-73 
MAKE FILE, 3-34 
OPEN FILE, 3-20 
PARSE FILENAME, 3-96 
PRINT BLOCK, 3-94 
PRINT STRING, 3-11 
READ CONSOLE BUFFER, 3-12 
READ FILE DATE STAMPS AND 

PASSWORD MODE, 3-81 
READ RANDOM, 3-48 



READ SEQUENTIAL, 3-29 
RENAME FILE, 3-36 
RESET DISK SYSTEM, 3-18 
RESET DRIVE, 3-56 
RETURN CURRENT DISK, 3-39 
RETURN DIRECTORY LABEL 

DATA, 3-80 
RETURN LOGIN VECTOR, 3-38 
RETURN SERIAL NUMBER, 3-88 
RETURN VERSION NUMBER, 

3-17 
SEARCH FOR FIRST, 3-24 
SEARCH FOR NEXT, 3-26 
SELECT DISK, 3-19 
SET BDOS ERROR MODE, 3-64 
SET DATE AND TIME, 3-85 
SET DEFAULT PASSWORD, 3-87 
SET DIRECTORY LABEL, 3-78 
SET DMA ADDRESS, 3-40 
SET FILE ATTRIBUTES, 3-44 
SET/GET USER CODE, 3-47 
SET MULTI-SECTOR COUNT, 

3-63 
SET RANDOM RECORD, 3-55 
SYSTEM RESET, 3-1 
TEST AND WRITE RECORD, 3-60 
TRUNCATE FILE, 3-76 
UNLOCK RECORD, 3-62 
WRITE FILE XFCB, 3-83 
WRITE PROTECT DISK, 3-42 
WRITE RANDOM, 3-50 
WRITE RANDOM WITH ZERO 

FILL, 3-59 
WRITE SEQUENTIAL, 3-31 

BIOS-resident, 3-46 

bit map, B-l 

bit vector, 3-43 

block size, 2-11 

blocking record, 3-63 

buffers, 1-2 

built-in commands, 1-18, 1-19 

Byte counts, 2-28 



Index-2 



) DIGITAL RESEARCH 7 



Call BIOS, 1-22 

call RSX, 3-74 

carriage return, 2-13, 3-2 

CCB format, 3-94 

CCP, 1-6, 1-7, 1-8, 1-11, 1-13 1-15, 

1-16, 1-27, 2-18 
chain flag, 3-67 
Chain to Program, 1-23, 3-67 
change default drive, 1-16 
Character Control Block CCB, 3-94, 

3-95 
character echo, 2-4 
check-sum vector, 2-27 
Close File, 2-17, 3-22 
Cold Boot Loader, 1-14 
cold start, 1-11, 1-14, 1-15 
COM, 2-11 
COM filetype, 1-20 
command drive field, 2-37 
command keyword, 1-17 
command line, 1-17, 2-37, 2-38 
command tail, 1-17 
common memory, 1-3 
common memory base address, 3-71 
common region size, 1-5 
compatibility, 1-22, 1-28 
Compute File Size, 2-28, 3-53 
conditional command, 1-23 
CONIN, 1-7, 2-3 
CONIN:, 3-2, 3-7 
CONOUT, 2-3 
CONOUT:, 3-3, 3-94 
console characteristics, 1-27 
console column position, 3-70 
Console Command Processor, 1-13 
console input, 1-26, 2-3, 3-2, 3-7 

mode, 3-70 
Console mode default state, 3-2 
Console output, 2-3, 3-3, 3-7 
console page length, 3-70 
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Console status, 2-3, 3-8 
console width, 3-70 

string output, 2-3 
context, 1-3 
control character ", 2-5 
copy file, 1-12, 4-1 
CP/M, 1-1, 1-2 
CP/M 2, 2-1 
CP/M version 2, 1-28 
CPM3.SYS file, 1-15 
CPMLDR, 1-14, 1-15 
CPMLDR BDOS, 1-14 
CPMLDR BIOS, 1-14 
create directory entry, 3-34 
create directory label, 3-80 
create stamp types, 2-24 
create XFCB, 3-34 
Creation date and time stamp, 3-35 
CTRL-A, 3-14 
CTRL-B, 3-14 
CTRL-C, 3-14 
CTRL-E, 3-14 
CTRL-F, 3-14 
CTRL-G, 2-4, 3-12, 3-14 
CTRL-H, 3-14 
CTRL-I, 3-3 
CTRL-J, 3-15 
CTRL-K, 3-15 
CTRL-M, 3-12, 3-13, 3-15 

return, 3-13 
CTRL-P, 3-15 
CTRL-Q, 2-4, 2-5, 3-3 
CTRL-R, 3-15 
CTRL-S, 2-4, 2-5, 3-3 
CTRL-U, 3-15 
CTRL-W, 3-15 
CTRL-X, 3-15 
CTRL-Z, 2-3 
current record, 2-15, 2-36 
current user number, 1-28 
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Data, 2-12 

area, 1-12, 2-12 

block size, 2-12 

space, 1-12 

tracks, 1-12 
data byte 

directory label, 3-78, 3-80 
date, 1-27, 3-70, 3-80 
Date and Time, 3-80, 3-81 
DATE utility, 2-25 
default disk, 1-15 
default DMA buffer, 2-35 
default drive, 1-16 
Default Error Mode, 3-64 
default FCB, 2-36 
default output delimiter, 3-93 
Default Password, 3-87 
Delete File, 2-17, 2-22, 3-27 
Delete XFCBs, 2-17 
delimiters, 1-17 
Delimiter output, 3-93 
DEVICE utility, 2-2 
differences: banked and nonbanked, 

1-1 
DIR, 1-18 

DIR.COM utility, 1-18 
Directory Code, 2-32 
direct BIOS calls, 1-22 
Direct Console I/O, 3-7 
Direct Memory Address, 3-40 
directory area, 1-12 
directory check-sum vector, 2-27 
Directory Code, 2-32, 2-33 
directory entries, 2-15 
directory functions, 2-7 
directory hash tables, 1-2, 1-4 
directory hashing, 2-27 
Directory Label, 2-19, 2-20 2-23, 3-24, 

3-79, 3-80 
directory label data byte, 3-78, 3-80 



Directory Label password, 2-21 
directory label 

create, 3-79 

update, 3-79 
directory space, 1-13 
DIRLBL.RSX, 1-25, 2-21, 3-78 
DIRSYS, 1-18 
disk access, 1-12 
disk change, 2-27 
disk directory area, 2-12 
Disk Drive Organization, 1-11 
disk formatting program, 1-22 
Disk I/O error, 2-29 
Disk organization, 2-11 
Disk Parameter Block, 3-46 
disk record buffers, 1-2, 1-4 
Disk Reset Function, 2-27 
disk space, 1-13 
Disk current, 3-71 
disk select, 2-29 
DMA 

address, 3-70 

buffer 

default address, 2-35 
DPB 

address, 3-46 

Disk Parameter Block, 3-46 
drive A, 1-14 

drive allocation vector, 2-27 
drive capacity, 2-11 
drive chain, 1-20 
drive code, 2-14 
drive functions, 2-8 
drive reset, 2-27 
drive search chain, 3-71 
drive select code, 2-9 
drive specification, 1-17 
drive support, 1-11 
drives 

Read-Only, 3-43 
Dump file, 4-5 
dynamic allocation, 1-13 
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edit control characters, 3-14 
empty directory entry, 2-16 
end-of-file, 2-3 
ERASE, 1-18 
error codes, 2-30, 3-23 
Error Flag, 2-30, 2-33 
Error Handling, 2-28 
error messages, 2-30 
error mode, 3-71 
Error mode 

default, 2-29, 3-64 

return, 2-29, 3-64 

return and display, 2-29 

return code, 3-70 

Set, 3-64 
error 

? in Filename, 2-30 

File Exists, 2-30 

Invalid Drive, 2-29 

Read-Only, 2-29 
expanded error message, 2-29 
extend operating system functions, 1-9, 

1-24 
extended error codes, 2-33, 3-21 
extended errors, 2-29, 2-30 
extended FCB, 2-19 
extent 0, 3-48, 3-50 
extent field format, 3-83 
extent number, 2-14 



file 

access, 2-7 

attributes, 2-16 

byte count, 2-28, 3-44 

Control Block, 2-13 

File 

Control Block, FCB, 2-13 

default, 2-36 

directory elements, 2-15 

Dump, 4-5 

Exists error, 2-30 

format, 2-13 

identification, 1-12 

naming conventions, 2-11 

organization, 2-11 

Password error, 2-30 

passwords, 2-23 

size, 3-53 

space allocation, 1-13 

specification, 2-9 

type field, 2-9, 2-10 
filename, 1-13, 1-17, 2-9, 2-14 
Filename 

parse, 3-96 
filespec, 1-17 
filetype, 1-13, 1-17, 2-14 
Flush Buffers, 2-25, 2-33, 3-68 
Free Blocks, 2-33 
Free Drive MP/M, 3-58 
Free Space Disk, 3-65 
function calls, 1-6 
functional BDOS, 2-4 



FCB, 3-20 

FCB format, 2-18, 3-98 

FCB 

length, 2-13 

default, 2-36 

parsed, 1-21 

random record field, 3-55 
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GENCOM, 1-9, 1-24, 2-6 

GENCPM, 1-2, 1-16 

generic filetypes, 2-11 

Get ADDR (Alloc), 2-34, 3-41 

Get Addr (Disk Parms), 2-34, 3-46 
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Get Console Mode, 3-91 

Get Console Status, 3-16 

Get Date and Time, 3-86 

Get Disk Free Space, 2-33, 3-65 

Get Output Delimiter, 3-93 

Get Program Return Code, 3-89 

Get Read-Only vector, 3-43 

GET RSX, 2-6 

Get User Code, 3-47 

GET utility, 1-24, 1-26 

GET.COM, 1-24, 1-26 

GET.RSX, 1-24 

Get/Set Console Mode, 2-5, 3-91 

Get/Set Output Delimiter, 2-5, 3-93 

Get/Set Program Return Code, 1-23, 

3-89 
graphic characters, 3-2 



H 

hard disks, 1-11 

hash tables, 1-4, 2-27 

HEX, 2-11 

highest memory address, 2-35 
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INITDIR utility, 2-24, 3-79 
initializing an FCB, 2-16 
input buffer format, 3-12 
INT, 2-11 
Intel PL/M systems programming 

language, 2-1 
interface attributes, 2-17, 3-22 
internal date and time, 3-86 
Invalid Drive error, 2-29 



K 

key fields, 3-55 



line editing, 2-4 

line feed, 2-13, 3-2 

Link-80, B-2 

List Block, 3-95 

list device, 2-4, 3-2 

List Output, 3-6, 3-70 

Load Overlay, 1-9, 1-24 

load RSX, 1-9, 1-24 

LOADER, 1-6, 1-9, 1-11, 1-21, 1-24 

LOADER module, 1-24, 3-73, 4-21 

LOADER size, 1-11 

LOADER base, 1-9, 1-10 

Lock Record, 3-61 

logged-in state, 2-27 

logging-in the drive, 2-27 

logical AUXIN, 2-2 

logical AUXOUT, 2-2 

logical CONIN, 2-2 

logical CONOUT, 2-2 

logical device names, 2-2 

logical drive, 1-11, 2-12 

logical LST, 2-2 

Logical Memory Organization, 1-5 

logical record size, 2-25 

LST, 2-3, 2-6 

LST:, 3-2, 3-6, 3-95 



M 

Make File, 2-17, 3-34 
Make File function, 2-17 
Make Write File XFCB, 2-20 
maximum filesize, 1-11, 2-11 
maximum memory, 1-2 
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maximum memory address, 1-10 
maximum record count, 3-53 
maximum TPA address, 1-21 
media change, 2-27 
memory map, 1-14 
memory maximum, 1-2 
memory organization, 1-1 
Memory Region Boundaries, 1-9 
memory regions, 1-9 
miscellaneous functions, 2-7 
modify file attribute byte count, 3-44 
modify operating system functions, 1-9, 

1-24 
modules of operating system, 1-5 
MP/M, 1-19, 1-28, 2-1, 3-17 
multi-sector count, 2-26 3-30, 3-71 
multi-sector I/O, 2-26 
multiple file reference, 1-13 
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next record, 3-55 

nonbanked Memory Organization, 1-2 

nonbanked systems, 1-2 

null byte, 3-67 

null command file, 1-24 



o 

open file, 2-22 

operating system modules, 1-5 
output delimiter, 3-70, 3-93 
overlay, 3-73 



page, 1-10 

alignment, 1-11 
boundaries, 1-10 



mode, 3-70 

Relocatable, 1-19 

Relocatable files, 1-24 

Relocatable Program, B-l 

Zero, 1-5, 1-7, 1-15, 1-20 1-23, 
1-25, 2-1, 2-35 

Zero fields, 1-21, 2-38 
Parameter Block 

BIOS, 3-72 

RSX, 3-74 

SCB, 3-69 
Parse Filename, 2-9 
Parse Filename Control Block PFCB, 

3-96 
parse procedure, 1-19 
parsed FCB, 1-21 
Partial close, 2-17, 3-22 
password, 1-1, 1-13, 1-17, 1-19, 2-22 
password address, 2-35 
password field, 2-9, 2-16, 2-35, 2-38 
password length, 2-35, 2-36 
password mode, 3-83 
Password Protection Modes, 2-22 
password support, 1-1 
password 

assign, 2-17 

default, 2-23, 3-87 
permanent close, 3-22 
physical drive, 1-11 
physical error, 2-29, 2-31 
physical error codes, 2-34, 3-19, 3-21, 

3-23 
physical file size, 3-53 
physical record size, 2-25 
PIP command, 1-12 
PIP utility, 2-17 
PL/M, 2-1 
PLI, 2-11 
Print Block, 3-94 
Print String, 2-5, 3-11 
printer echo, 2-4, 2-5, 3-2 
PRL, 2-11, 3-73 
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PRL file, 1-19, 1-24 
PRL File Fprmat, B-l 
PRL filetype, 1-20 
PRN, 2-11 

PROFILE submit file, 1-16 
PROFILE.SUB, 1-16 
Program chain, 1-23, 3-67 
Program Return Code, 1-23 
PUNCH, 2-6 
Purge flag, 3-68 



question mark, 1-13, 2-11 



R 



Random Access, 4-10 

random file, 2-12 

random record field FCB, 3-55 

random record number, 2-12, 2-13 

random record position, 2-36 

Read Buffer Input, 2-4 

read character, 3-2 

Read Console Buffer, 3-12 

read edited console input, 3-12 

read next record, 3-29 

Read random, 2-30, 3-49 

Read Sequential, 2-30, 3-29 

Read-Only, 3-42 

Read-Only attribute, 2-16 

Read-Only Disk error, 2-29 

Read-Only drives, 3-43 

Read-Only File error, 2-29 

READER, 2-6 

record, 2-12 

record blocking, 2-25, 3-63 

record count, 2-14 

record deblocking, 2-25 

record size, 2-7 



Record 

Lock, MP/M II, 3-61 

Unlock, MP/M II, 3-62 
redirected input, 1-27 
region boundaries, 1-9 
register A, 2-30 
REL, 2-11 

relocatable module, 3-73 
remove file, 2-22 
Remove flag RSX, 1-25 
remove RSX, 1-25 
RENAME, 1-18 
Rename File, 3-36 
reset disk system, 1-22, 3-18 
reset drive, 2-27, 3-56 
resident operating system module, 1-2 
resident portion, 1-2 
Resident System Extension, 1-6, 1-9, 

1-13, 1-24, 4-20 
Return and Display Error Mode, 3-64 
Return Code Program, 3-89 
return codes, 2-30 
Return Current Disk, 3-39 
Return Directory Label, 2-21 
Return Directory Label Data, 2-33, 

3-80 
Return Error Mode, 3-64 
Return Login Vector, 3-38 
return modes, 3-64 
Return Serial Number, 3-88 
Return Version Number, 3-17 
RSX, 1-6, 1-8, 1-9, 1-11, 1-22 1-23, 
1-24, 1-26 

active, 1-9 

File Format, 1-25 

flags, 1-25 

header, 1-9, 1-21, 1-25, 3-73 

Parameter Block, 3-74 

prefix, 4-20 

programs, 4-20 

removal, 1-25 
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rub/del 
remove last character, 3-13 



SCB, 1-27 

SCB parameter block, 3-71 

scroll output, 2-4 

support, 2-5 
Search For First, 3-24 
Search For Next, 3-24, 3-26 
sectors, 3-65 

select disk, 2-29, 2-33, 3-19 
sequential file, 2-12 
sequential I/O processing, 2-26 
serial device I/O, 2-2 
serial number, 3-88 
SET BDOS Error Mode, 3-64 
Set Console Mode, 3-91 
Set Date and Time, 3-85 
Set Default Password, 2-23, 3-87 
Set Directory Label, 1-25, 2-21, 2-23, 

3-79 
SET DMA Address, 3-40 
Set Error Mode, 2-29 
Set File Attributes, 2-17, 2-22, 2-28, 

3-44 
set file byte count, 2-17 
Set/Get User Code, 3-47 
Set multi-sector count, 2-26, 3-63 
Set Output Delimiter, 3-93 
Set Program Return Code, 3-89 
Set Random Record, 3-53 
Set User Code, 3-47 
SETDEF utility, 1-19, 1-20, 1-27 
SFCB, 2-23, 3-79 
sign-on message, 1-14 
size 

BDOS, 1-11 

common region, 1-5 

compute File BDOS, 3-53 



LOADER, 1-11 

record, 2-7 

transient program, 1-11 
Source files, 2-13 
space 

Disk, 3-65 
Sparse files, 2-12 
SPR, 2-11 

Standard Delete, 3-27 
standard search, 3-24 
start scroll, 3-2 
stop scroll, 3-2 
SUB filetype, 1-19 
SUBMIT, 1-19 
submit command line, 1-27 
submit file, 1-15, 1-19, 1-20, 1-27 
SUBMIT RSX, 1-27 
SUBMIT utility, 1-13, 1-27 
SYM, 2-11 
SYS, 2-11 
System 

Attribute, 2-17 

cold start, 1-11, 1-12, 1-14 

communication, 1-7 

components, 1-5 

Control Block, 3-70 

date and time, 2-23 

generation, 1-15 

Interaction, 1-7 

modules, 1-5 

Operation, 1-13 

prompt, 1-13, 1-16, 1-28 

regions, 1-5 

reset, 1-22, 3-1 

tracks, 1-12, 1-15 

warm start, 1-11, 1-12, 1-15 
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tab characters, 3-2 

tab expansion, 2-3, 2-5 

temporarily-allocated data block, 3-75 

temporary drive, 3-71 

temporary file drive, 1-27 

temporary submit file, 1-27 

terminate execution, 1-23 

terminate program execution, 1-8, 1-23 

Test and Write Record, 3-60 

TEX, 2-11 

time, 1-27 

Time and Date, 3-85 

TPA, 1-7, 1-8, 1-11, 1-15, 1-21, 1-22 

transient program, 1-7, 1-11, 1-13, 

1-19, 1-22 
Truncate File, 2-22 
TYPE, 1-18 
types of file stamps, 2-23 
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Unlock Record MP/M, 3-62 
update date and time stamp, 3-34, 

3-50 
update directory label, 3-78 
update stamp types, 2-23 
USER, 1-18 
user 0, 2-18 
User file access, 2-18 
USER command, 1-12 
user directories, 2-18 
user number, 1-15, 1-20, 1-28 2-18, 

3-47 
User number conventions, 2-18 
user numbers, 1-12 



version number, 3-70 
virtual file size, 3-53 



w 

warm start, 1-11, 1-15, 1-22, 1-23, 

1-26, 3-1 
wildcard characters, 1-13 
write data record, 3-31 
Write File XFCB, 2-22 
Write Protect Disk, 3-42 
Write Random function, 2-30, 3-50 
Write Random with Zero Fill, 2-30, 

3-59 
Write Sequential, 2-31, 3-31 
write-pending records, 3-68 
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XFCB, 2-19, 2-20, 2-23, 3-27 



Zero Fill Write Random, 3-59 



Index-10 



DIGITAL RESEARCH 7 



Reader Comment Form 

We welcome your comments and suggestions. They help us provide you with better 
product documentation. 

Date Manual Title Edition 

1. What sections of this manual are especially helpful? 



2. What suggestions do you have for improving this manual? What information 
is missing or incomplete? Where are examples needed? 



3. Did you find errors in this manual? (Specify section and page number.) 



COMMENTS AND SUGGESTIONS BECOME THE PROPERTY OF DIGITAL RESEARCH. 



NO POSTAGE 
NECESSARY 
IF MAILED IN THE 
UNITED STATES 



BUSINESS REPLY MAIL 

FIRST CLASS / PERMIT NO. 182 / PACIFIC GROVE, CA 
POSTAGE WILL BE PAID BY ADDRESSEE 

D DIGITAL RESEARCH™ 

P.O. Box 579 

Pacific Grove, California 

93950 



Attn: Publication Production 



